Create Patient

Create a new patient record. If a patient with the same identity already exists, the existing record is returned with code 2301 instead of creating a duplicate.

Endpoint

POST /apis/v1/patient

Request Body

Parameter	Type	Required	Description
first_name	string	Yes	Patient's first name
last_name	string	Yes	Patient's last name
middle_name	string	No	Patient's middle name
alias	string	No	Known name or alias
date_of_birth	string (date)	Yes	Date of birth (YYYY-MM-DD)
sex	string	Yes	MALE, FEMALE, OTHER, OTHERS, or UNDEFINED
mobile	string	No	Primary phone number (max 16 digits)
secondary_contact	string	No	Secondary phone number (max 16 digits)
email_address	string	No	Email address
address	object	No	Mailing address (see Address Object)
clinic_id	integer	Yes	ID of the clinic to add the patient to
status	string	No	Initial status. One of CREATED, ACTIVE, INACTIVE, DELETED, LEAD, DISCHARGED. Defaults to CREATED.

Address Object

Parameter	Type	Required	Description
line1	string	No	Street address line 1
line2	string	No	Street address line 2
city	string	No	City
state	string	No	2-letter USPS state code (e.g. CA, TX)
postal_code	integer	No	ZIP / postal code

Request

curl --location '{base_url}/apis/v1/patient' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Jane",
    "middle_name": "Marie",
    "last_name": "Smith",
    "alias": "Janey",
    "date_of_birth": "1985-03-15",
    "sex": "FEMALE",
    "mobile": "5551234567",
    "secondary_contact": "5559876543",
    "email_address": "jane.smith@example.com",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "Springfield",
      "state": "IL",
      "postal_code": 62701
    },
    "clinic_id": 44,
    "status": "ACTIVE"
  }'

Response

Success — New Patient Created

Code: 200 OK

{
  "code": 2000,
  "data": {
    "patient_id": 10234,
    "name": "Jane Smith",
    "first_name": "Jane",
    "middle_name": "Marie",
    "last_name": "Smith",
    "suffix": "",
    "alias": "Janey",
    "date_of_birth": "1985-03-15",
    "sex": "FEMALE",
    "mobile": "5551234567",
    "secondary_contact": "5559876543",
    "photo_url": null,
    "email_address": "jane.smith@example.com",
    "height": null,
    "weight": null,
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "landmark": "",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "latitude": null,
      "longitude": null,
      "gps_link": null,
      "country": null,
      "plus_code": null,
      "place_id": null
    },
    "relation": null,
    "user": {
      "user_id": 58001,
      "username": "USR1234567890123456",
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "mobile": "5551234567",
      "organisation_id": 74
    },
    "poc_status": null,
    "status": "ACTIVE",
    "comorbidities": [],
    "external_ref_id": null,
    "speciality_list": [],
    "organisation_id": 74,
    "preferred_language": "ENGLISH",
    "legacy_patient": null,
    "total_visits": 0,
    "payment_mode": null,
    "emergency_contacts": null,
    "last_appointment_id": null,
    "source_system": null
  },
  "message": "Success"
}

Patient Already Exists

Code: 200 OK

When a patient with matching identity is found, code 2301 is returned with the existing patient's data. The patient_id is present and usable.

{
  "code": 2301,
  "data": {
    "patient_id": 10234,
    "first_name": "Jane",
    "last_name": "Smith",
    "status": "ACTIVE",
    "organisation_id": 74
  },
  "message": "Patient already exists"
}

Error Response

Code: 200 OK

{
  "code": 4000,
  "data": null,
  "message": "Invalid request"
}

Response Fields

Field	Type	Description
patient_id	integer	Unique ID of the created (or existing) patient
name	string	Full name (concatenated)
first_name	string	First name
middle_name	string	Middle name
last_name	string	Last name
suffix	string	Name suffix
alias	string	Known name or alias
date_of_birth	string (date)	Date of birth
sex	string	Biological sex
mobile	string	Primary phone number
secondary_contact	string	Secondary phone number
photo_url	string	Patient photo URL
email_address	string	Email address
height	string	Height
weight	string	Weight
address	object	Patient's address
relation	string	Relationship context
user	object	Linked system user account
poc_status	string	Point-of-care status
status	string	Patient status
comorbidities	array	Comorbidity entries
external_ref_id	string	External reference ID
speciality_list	array	Associated specialities
organisation_id	integer	Organisation ID
preferred_language	string	Preferred language
legacy_patient	object	Legacy migration data
total_visits	integer	Total completed visits
payment_mode	string	Payment mode
emergency_contacts	array	Emergency contacts
last_appointment_id	integer	Most recent appointment ID
source_system	string	Source system for migrated records

Notes

• Both 2000 and 2301 mean the patient record is available — patient_id is present in both. Treat any other code as a failure.
• clinic_id is mandatory. Use List Clinics to retrieve valid IDs.
• Phone fields accept up to 16 digits.
• state must be a valid 2-letter USPS abbreviation.