Skip to main content
The Orgo API answers in JSON-LD or plain JSON and accepts JSON request bodies. The format is chosen by the 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:
The data is the same. JSON-LD adds the @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:
Plain JSON returns just the array:
You lose 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.
For ad-hoc scripting and one-off integrations, plain JSON is shorter and easier to consume. For data-pipeline integrations that paginate through everything, JSON-LD is usually worth the slightly noisier envelope.

Request formats

PATCH and merge-patch

Always send Content-Type: application/merge-patch+json for PATCH. The endpoint only updates the fields you include; missing fields are left untouched.
Sending 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:
This works for both JSON and JSON-LD requests. A nested object in place of the IRI is accepted on some endpoints, but it is slower and more error-prone, so prefer IRIs. Some resources are addressed by a 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).
The answer carries 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}.
The name is signed for the caller and the type that asked for it. A name that was not issued to you for that type, an old name from before a deployment, or a file that was never uploaded is refused with 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 Accept for the full JSON-LD view, or set Accept: application/json for cleaner output.
  • You’re writing an integration: Accept: application/json for reads, Content-Type: application/json for writes, Content-Type: application/merge-patch+json for 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.