---
title: "Send patients and visits to Practor from your own system"
summary: "Register patients under your own patient number, record their insurance, and send each finished visit with its diagnosis and procedure codes."
source: https://practor.app/en-za/help/security-and-integrations/send-patients-and-visits-to-practor-from-your-own-system
published: 2026-09-29T07:17:43.900Z
updated: 2026-10-01T18:08:42.855Z
category: "Security and integrations"
---

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](/help/security-and-integrations/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](https://developers.practor.app/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:

```json
{
  "givenNames": ["Thandi"],
  "lastName": "Mokoena",
  "gender": "female",
  "birthDate": "1985-06-12",
  "externalId": { "system": "urn:your-clinic:patient", "value": "12345" },
  "contactPoints": [{ "system": "email", "value": "thandi@example.com" }]
}
```

Every field you can send for a patient is on the [register a patient](https://developers.practor.app/reference/patients/patient-create) 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:

```json
{
  "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](https://developers.practor.app/reference/coverage/coverage-create) 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](/help/security-and-integrations/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:

```json
{
  "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](https://developers.practor.app/reference/encounters/encounter-create) 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.

## Related

- [Connect your own software to Practor](/help/security-and-integrations/connect-your-own-software-to-practor)
- [Bill a visit and read back what it was paid](/help/security-and-integrations/bill-a-visit-and-read-back-what-it-was-paid)
- [Change an invoice and claim it from your own system](/help/security-and-integrations/change-an-invoice-and-claim-it-from-your-own-system)
- [Integration API errors and limits](/help/security-and-integrations/integration-api-errors-and-limits)