Base URL
Production https://api-ec2.connectai.care/master/integration/v1
Sandbox issued with your sandbox credentialsEndpoints
/pingLiveHandshake. Verifies your signature and returns the bound clinic and our server time.
/patientsLiveUpsert one patient.
/availabilityLiveReplace a doctor's weekly schedule. Identify them with doctorPhone.
/appointmentsLiveRegister an appointment booked in your system.
/appointments/{externalId}LiveReschedule, or change status.
/appointments/{externalId}/cancelLiveCancel, with a reason.
/lab-reportsLiveSend a lab report to the patient. See Documents.
/prescriptionsLiveSend a prescription to the patient. See Documents.
/documents/{externalId}LiveDid it reach the patient? Delivery status for one document.
/batchLiveUp to 100 of the above in one signed call.
No setup call
There is nothing to configure before you start. You do not register your doctors, patients or locations with us first — every endpoint resolves what it needs from the request itself and remembers the answer.
Doctors are identified by doctorPhone, the number they are registered under with the clinic. We match it to the clinic's roster; if you also send doctorExternalId, we remember it and you can use it alone from then on. We never create a doctor from your payload — if the number does not match anyone on the clinic's roster you get 409 doctor_unmapped and the clinic adds them.
Patients work the same way: send patientExternalId if you have mapped one before, otherwise patientPhone and patientName are enough. Unknown patients are created.
Conventions
externalId
Every resource you send carries an externalId — your own primary key for that record. We store the mapping between your id and ours, so you never have to look ours up. Responses return both.
It is also your idempotency handle: re-sending a document with the same externalId returns the first result rather than delivering it to the patient twice.
Identifiers and clinic scope
The clinic is taken from your key, never from the request body. A clinicId in a payload is ignored.
Dates and times
Send ISO 8601 with an explicit offset, for example 2026-09-25T10:15:00+05:30. We store UTC and return both a UTC timestamp and a local-time rendering. Never send a naive timestamp.
Phone numbers
E.164 only, for example +919811223344. Phone is also the fallback key we match a patient on when no mapping exists yet, so a badly formatted number is worse than a missing one.
Enumerated values
Send these exactly as written, including the space in Video Call. We do not accept synonyms — a lenient parser becomes an untraceable data-quality problem later.
| Field | Accepted values |
|---|---|
mode | Offline, Video Call, Audio Call, Chat, Virtual |
status | Pending, Approved, Rejected, Reschedule, Completed, Cancelled |
gender | Male, Female, Other |
Rate limit
120 requests per minute per key, with /batch counted as one request. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; going over returns 429 with Retry-After in seconds.
Idempotency
Send a unique X-ConnectAI-Event-Id per logical operation. If you retry with the same id, you get the original response back — same status, same ids — rather than a duplicate record. Without it, a retry after a network timeout can create a second appointment.