Endpoints
Ingest Endpoint
- Authentication: Bearer token in Authorization header.
- Body: JSON payload (see Field Mapping).
- Rate limits: Default is 120 requests/minute.
- Responses:
- 200 Accepted Request - stored and queued for processing.
- 422 Unprocessable Entity - Validation failed.
- 401 Unauthorized - Invalid/expired/missing token.
- 429 Too Many Requests - Rate limit exceeded.
Global Ingest Endpoint
The global endpoint lets you send payloads for any of your ingest endpoints to a single URL, without the endpoint UUID in the path. Instead of routing by URL, Jomablue resolves the target endpoint from an identifier included in the payload body. This is useful when the sending system can only post to one fixed URL but can vary the identifier per request.
- Identifier key: By default the payload must include an ingest_uuid field at the top level. This key is configurable per instance, so confirm the exact key for your instance with Jomablue.
- Identifier value: May be either the ingest endpoint's UUID or its configured organisation_uid.
- Authentication, rate limits, and responses: Identical to the standard ingest endpoint above. Once the endpoint is resolved, the payload is validated and queued in exactly the same way.
Example payload:
If the identifier is missing or does not match a known endpoint, the request is rejected with a 422 response:
- Missing identifier - The provided payload does not include an ingest id - The id should be provided in the node: ingest_uuid
- No match - There is no match for the ingest id provided.
Ingest Test Endpoint
This validates a payload without persisting it. Use this to check whether a request would be accepted by the configured mapping and validation rules. Available only for People type ingesting.
Validation
Ingest endpoints can be configured with customised schema validation. This reduces bad data by rejecting invalid requests early. If a request fails to pass validation, a 422 response is provided with some additional messaging.
Considerations
- Requests are processed asynchronously - 200 Accepted means queued, not processed.
- No automatic deduplication; upstream systems should send unique identifiers (organisation_uid) if required.
- Event ordering is not guaranteed; jobs are processed as picked from the queue.
- People Import type is labeled as ingest_api in reporting so you can understand which records were ingested via this API.
- The global endpoint (POST /api/webhook/ingest) resolves the target endpoint from an identifier in the payload (default key ingest_uuid, matching the endpoint's UUID or organisation_uid) rather than from the URL.