Accept and Content-Type headers. Files are not sent to the API as multipart bodies: they go straight to storage through a signed upload, and the API call that follows carries only a reference. See File uploads.
For most integrations, plain application/json is the right choice. Use JSON-LD when you need pagination metadata or generic link discovery.
Response formats
If you do not send an
Accept header, JSON-LD is returned. The server also lists multipart/form-data as a configured format, but no documented endpoint produces or consumes it, so ignore it.
Example: the same resource, two ways
GET /api/v1/users/42 returns one of these depending on the Accept header:
- JSON-LD (default)
- Plain JSON
@context, @id and @type wrapping that lets generic clients reason about the response without knowing the schema in advance. Which fields appear depends on who is asking: a field you are not allowed to see is left out.
Error bodies follow their own shapes, listed in Errors.
The Hydra collection envelope
JSON-LD collections are wrapped in a Hydra envelope that carries totals and pagination links:hydra:totalItems and the next-page links in plain JSON. If you need to display “showing 60 of 1,248” or iterate every page, use JSON-LD.
Request formats
PATCH and merge-patch
Always sendContent-Type: application/merge-patch+json for PATCH. The endpoint only updates the fields you include; missing fields are left untouched.
null for a field clears it where the field is nullable. Sending an empty string stores the empty string.
Many action endpoints (publish, send, close, archive, and so on) are PATCH or POST calls with an empty body. Send {} with the matching content type.
Referencing other resources
For relations, send the IRI (the resource’s address) of the target:uuid, others by an integer id; use whatever the @id of the resource you read shows.
Dates and times are ISO 8601 strings (2026-03-15T18:00:00+00:00). Fields stored as calendar dates only, such as a date of birth, use YYYY-MM-DD.
File uploads
Files never pass through the API as request bodies. The pattern has three steps, and the third is an ordinary JSON call:1
Ask for a signed upload
GET /api/v1/s3-upload with the query parameters type (what the file is for, for example identity, adhesion, drive, customfield, eventimage, postimage), fileType (the MIME type) and fileName. Which types you may use depends on who you are: anonymous callers get only a few (a registration form’s file field, for instance).url (where to upload), additionalData (form fields that must accompany the file) and newFileName (the name the file will have). The signature is valid for 15 minutes and the key is fixed to newFileName, so you cannot choose another one. Uploads are capped at 1 GB, and executable and HTML types are refused.2
Upload the file to the signed address
Send a
multipart/form-data POST to the url from step 1, with every additionalData field first and the file last, in a field named file. This request goes to storage, not to the Orgo API.3
Tell Orgo about the file
Call the endpoint that attaches the file, with a JSON body naming it. For adhesions,
POST /api/v1/adhesion/{id}/upload-signed takes {"contentUrl": "<newFileName>", "fileMimeType": "application/pdf", "fileSize": 184320}.400 and the message Upload the file before saving it. The fix is to start again from step 1. You cannot point an endpoint at an arbitrary file already in storage.
When in doubt
- You’re writing a curl by hand: omit
Acceptfor the full JSON-LD view, or setAccept: application/jsonfor cleaner output. - You’re writing an integration:
Accept: application/jsonfor reads,Content-Type: application/jsonfor writes,Content-Type: application/merge-patch+jsonfor partial updates, and the signed-upload pattern for files. - You’re building a generic client over the API: stay on JSON-LD throughout so you get the link relations.
Related
- Pagination and filters: how to iterate collections
- Errors: error envelope shapes

