Create Patient

Creates a patient. Requires a name, date of birth, one clinic, and either a mobile number or an email address.

Endpoint

POST /v2/patients

Request Body

Parameter	Type	Required	Description
first_name	string	Yes
last_name	string	Yes
date_of_birth	string (date)	Yes	YYYY-MM-DD.
clinic_ids	array of string	Yes	Clinics this record is associated with.
email	string	No
mobile	string	No
middle_name	string	No
suffix	string	No
gender	string	No	Administrative gender, matching FHIR Patient.gender — used for demographics and claims, not a clinical assertion. One of MALE, FEMALE, OTHER, UNKNOWN.
address	object	No	See Address.
preferred_language	string	No	ISO 639-1 language code.

Address

Parameter	Type	Required	Description
line1	string or null	No
line2	string or null	No
city	string or null	No
state	string or null	No
postal_code	string or null	No
country	string or null	No

Request

curl --location '{base_url}/v2/patients' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Jordan",
  "last_name": "Whitfield",
  "date_of_birth": "1991-07-23",
  "clinic_ids": [
    "5831"
  ],
  "email": "jordan.whitfield@example.com",
  "mobile": "+1-555-0168",
  "middle_name": null,
  "suffix": null,
  "gender": "MALE",
  "address": {
    "line1": "482 Willow Creek Rd",
    "line2": null,
    "city": "Fairview",
    "state": "OR",
    "postal_code": "97024",
    "country": "US"
  },
  "preferred_language": "en"
}'

Response

Success Response

Code: 201 Created

{
  "patient_id": "63120",
  "first_name": "Jordan",
  "middle_name": null,
  "last_name": "Whitfield",
  "suffix": null,
  "date_of_birth": "1991-07-23",
  "gender": "MALE",
  "email": "jordan.whitfield@example.com",
  "mobile": "+1-555-0168",
  "address": {
    "line1": "482 Willow Creek Rd",
    "line2": null,
    "city": "Fairview",
    "state": "OR",
    "postal_code": "97024",
    "country": "US"
  },
  "preferred_language": "en",
  "status": "ACTIVE",
  "organisation_id": "7412",
  "clinic_ids": [
    "5831"
  ],
  "provider_ids": [
    "2094"
  ],
  "secondary_contact": null,
  "photo_url": null,
  "height": null,
  "weight": null,
  "created_at": "2026-08-27T14:30:00Z",
  "updated_at": "2026-08-27T14:30:00Z"
}

The Location header carries the URL of the created resource.

Response Fields

Field	Type	Description
patient_id	string	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
first_name	string
middle_name	string or null
last_name	string
suffix	string or null
date_of_birth	string (date) or null	YYYY-MM-DD.
gender	string or null	Administrative gender, matching FHIR Patient.gender — used for demographics and claims, not a clinical assertion. One of MALE, FEMALE, OTHER, UNKNOWN.
email	string or null
mobile	string or null
address	object or null	See Address.
preferred_language	string or null	ISO 639-1 language code.
status	string	One of CREATED, ACTIVE, INACTIVE, DISCHARGED.
organisation_id	string or null	The organisation this record belongs to. Derived from the access token on writes and never trusted from the body.
clinic_ids	array of string	Clinics this record is associated with.
provider_ids	array of string	Providers associated with this record.
secondary_contact	string or null
photo_url	string or null	A fetchable URL. It may be a time-limited signed URL, so fetch it rather than storing it.
height	string or null
weight	string or null
created_at	string (date-time) or null
updated_at	string (date-time) or null

Address

Field	Type	Description
line1	string or null
line2	string or null
city	string or null
state	string or null
postal_code	string or null
country	string or null

Error Response

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	code	Meaning
400 Bad Request	bad_request	The request body or parameters failed validation. errors[] names the offending fields.
401 Unauthorized	unauthorized	The access token is missing, malformed or expired.
403 Forbidden	forbidden	The request references a resource outside the token's organisation or clinic scope.
404 Not Found	not_found	No such resource, or it's outside your scope.
429 Too Many Requests	rate_limited	Rate limit exceeded. Back off and retry.
500 Internal Server Error	internal_error	Unexpected server error.
502 Bad Gateway	upstream_error	Upstream service failed or timed out.