Skip to main content

Send patients and visits to Practor from your own system

Register patients under your own patient number, record their insurance, and send each finished visit with its diagnosis and procedure codes.

4 min read Updated 1 October 2026
On this page

This is for the person building the connection. The practice creates an integration client and gives you its key; Connect your own software to Practor covers what the practice does.

Call the API

Send every request to https://dashboard.practor.app/api/v1, with the key in the Authorization header. The key says which practice you're working for, so every practice uses the same address. The practice can copy this address and a first request to try from Connect, on the client's Overview tab in its settings.

Authorization: Bearer prk_live_...
Content-Type: application/json

Every record has its kind in object and its own id, and points at other records by their ids, like patientId. Values from a fixed list are lowercase, like female or self_pay.

The API reference has every request you can make and every field in it. To generate a client from the OpenAPI document, point your generator at https://dashboard.practor.app/api/v1/openapi.json, which needs no key.

Send an Idempotency-Key header with every POST, a new key for each record you create. If a request times out, send it again with the same key: you get back the record the first request created, and nothing is created twice.

Find the practitioner

  1. GET /api/v1/practitioners lists the practitioners a visit can be recorded under.
  2. Keep the id of each one. Each visit you send names its practitioner by that id.

Register a patient

POST /api/v1/patients with the patient:

{
  "givenNames": ["Thandi"],
  "lastName": "Mokoena",
  "gender": "female",
  "birthDate": "1985-06-12",
  "externalId": { "system": "urn:your-clinic:patient", "value": "12345" },
  "contactPoints": [{ "system": "email", "value": "[email protected]" }]
}

Every field you can send for a patient is on the register a patient page. A patient needs a lastName, at least one of givenNames, and a birthDate written YYYY-MM-DD. Put your own patient number in externalId, with a system that names your software. ID and passport numbers go in identifiers, each with a type, such as ppn for a passport.

Find a patient again with GET /api/v1/patients?externalSystem=urn:your-clinic:patient&externalId=12345, or read one with GET /api/v1/patients/{patientId}. A second patient with the same externalId is refused with a 409 that names the first one.

To record which practitioner registered the patient, send their id in an X-Practor-Performer header.

To change a patient, PUT /api/v1/patients/{patientId} with the whole patient. You can send back what a GET gave you, with your changes in it. Names, phone numbers, email addresses and physical addresses are replaced with what you send.

Registering a patient through the API sends them nothing. The practice sends any invitation.

Record a patient's insurance

POST /api/v1/coverages with the coverage:

{
  "patientId": "k3v9x2m8q1w7e4r6t0y5u2ia",
  "type": "insurance",
  "memberNumber": "900123456",
  "dependentCode": "01",
  "relationship": "self",
  "planId": "n6m1b5v8c2x4z7a9s3d0f5gh"
}

Medical insurance needs the memberNumber and the plan. If either is missing, the answer is a 422 that says which. relationship is one of self, spouse, child, parent, common, other or injured. For a patient who pays for themselves, send "type": "self_pay" with only patientId.

Find the plan with GET /api/v1/insurance-plans?name= and part of its name, or ?optionCode= and its option code. You can also leave planId out and send the option code as planOptionCode. Practor sets the insurer from the plan. The record insurance page has the rest of the fields.

GET /api/v1/coverages?patientId={patientId} lists a patient's insurance. To change one, such as a new member number, PUT /api/v1/coverages/{coverageId} with the whole coverage. To check a cover with the insurer before you claim, see Change an invoice and claim it from your own system.

Send a finished visit

POST /api/v1/encounters with the visit, its diagnoses and its procedures:

{
  "patientId": "k3v9x2m8q1w7e4r6t0y5u2ia",
  "practitionerId": "p4n8b6r2t9y3u7i1o5a0s8dm",
  "start": "2026-10-01T09:00:00+02:00",
  "end": "2026-10-01T09:45:00+02:00",
  "diagnoses": [{ "code": "M54.56" }],
  "procedures": [{ "code": "72001", "diagnosisCodes": ["M54.56"] }]
}

Put in the visit's own start and end times, and codes from the practitioner's own diagnosis and procedure code sets. A visit needs at least one diagnosis and one procedure. List diagnoses in order, the main one first. Each procedure's diagnosisCodes names the diagnoses it's billed against, by the codes you sent in diagnoses. Send each code's system, or leave it out to use the one the practitioner uses in Practor.

The record a visit page has every field a visit takes. If any code is unknown, the whole visit is refused, with every unknown code listed, and nothing is saved. The visit can't end in the future or start more than 120 days ago. A procedure can have one note of up to 1,000 characters; the rest of the clinical record stays in your system.

GET /api/v1/encounters/{encounterId} reads a visit back. GET /api/v1/encounters?patientId={patientId} lists a patient's visits, newest first, 50 at a time. While hasMore is true, send nextCursor back as cursor for the next page.

Was this helpful?

Next in Security and integrations

Bill a visit and read back what it was paid Ask Practor to invoice a visit your system sent, issue it and claim from the insurer in the same call, then read the claim's outcome and the payments back. 4 min read