OlivIA API overview

Overview of the OlivIA API: channels, environments, authentication, and integration conventions

The OlivIA API lets an external system —an EHR/HIS, a CRM, or your own backend— integrate Omniloy’s clinical voice follow-up: enroll patients in protocols, read the outcome of each call, and receive real-time events.

Two channels

OlivIA works in two directions. The API focuses on the part an integrator needs to drive and read:

• Outbound calls — follow-up. You enroll a patient in a protocol and OlivIA calls them to complete the follow-up questionnaire, with automatic scheduling and retries. Driven from the API.
• Inbound calls — triage. A phone number is configured so that, when the patient calls, OlivIA runs a triage questionnaire. The number is set up with the Omniloy team; results arrive through the same read endpoints and webhooks.

Follow-up flow (outbound)

Triage flow (inbound)

Environments

Environment	URL
Production	https://{your-prod-endpoint}
Staging	https://{your-dev-endpoint}

Contact [e-mail] to get your credentials and your tenant’s real URLs.

Base path and version

All endpoints live under the /v1 prefix. For example:

https://{your-prod-endpoint}/v1/protocols

Authentication

Every operation uses a personal API key as a bearer token:

Authorization: Bearer oc_sk_...

See the Authentication guide.

Response format

Successful responses wrap the payload in data:

{ "data": { "id": "…" } }

Lists add pagination:

{ "data": [ … ], "pagination": { "total": 128, "limit": 50, "offset": 0 } }

Every response carries an x-request-id header, useful for support and tracing.

Errors

Errors use a single envelope:

{ "error": { "code": "validation_error", "message": "Invalid request", "details": [] } }

HTTP status	When
400	Invalid request (validation_error with details)
401	Missing or invalid API key
403	The key lacks the role required for the operation
404	Resource not found or not owned by your organization
409	State conflict (e.g. archiving a protocol with active enrollments)