Patients

Create Patient for clinic

⚕️ Patient Creation — Field Reference

This endpoint creates new patient records for a single clinic. All validations follow CreatePatientDto constraints.

🛡️ Security

Headers

Field	Type	Description	Required
x-api-key	String	API Key for authentication	Y
clinicId	String	Clinic ID in header overrides route parameter	Y

🩺 Demographics

Patient Info

Field	Type	Description	Required
ext_userid	String	Optional unique identifier, this is user_id/username in client systems, will be used in callbacks to send information.	N
First Name	String	Letters only — mandatory	Y
Last Name	String	Letters, spaces, hyphens, apostrophes allowed — mandatory	Y
Middle Name	String	optional	N
Date of Birth	String	Must follow ‘YYYY-MM-DD’ — mandatory	Y
Gender	String	’M’, ‘F’, or ‘O’ (case-insensitive) — mandatory	Y
isSmoker	boolean	Accepts ‘y/yes/true/n/no/false’ — optional	N
isPregnant	boolean	Same boolean pattern — optional	N
isDiabetic	boolean	Same boolean pattern — optional	N
heightInInches	Number	If provided needs to be a positive number — optional	N
weightInPounds	Number	If provided needs to be a positive number and below 600 lbs — optional	N

📞 Contact & Address

Contact

Field	Type	Description	Required
Email	String	Conditional mandatory — required only if SMS consent is not given.	Y
Phone	String	Must be 10 digits; ‘+1’ allowed — mandatory	Y

Address

Field	Type	Description	Required
Address1	String	Standard special characters are allowed. P O Boxes not allowed — mandatory	Y
Address2	String	If present standard special characters are allowed — optional	N
City	String	Standard special characters allowed for cities are allowed — mandatory	Y
State	String	US two character state codes are allowed — mandatory	Y
ZipCode	Number	Standard 5 digit zip code is allowed no characters are allowed — mandatory	Y

🆔 Identity

Identification

Field	Type	Description	Required
Driver License #	String	Encouraged to provide as it will be a mandatory field for Controlled Drugs.(future) — optional	Y
Driver License State	String	Required if license # is provided — valid US state code.	Y/N
SSN	String	mandatory if driver license number is not provided; must be valid SSN format — optional	Y/N

✍️ Consents

Field	Type	Description	Required
authSmsConsent	boolean	Boolean-style (‘y/yes/true/n/no/false’) — mandatory	Y
smsConsent	boolean	optional	N
dataRatesSmsConsent	boolean	Defaults to true — optional	N

🧬 Risk Factors [allergies, conditions, medications]

Risk Factors

Field	Type	Description	Required
riskFactors	JSON	Object includes allergies, medications, conditions. Must follow validation rules — mandatory	Y
allergies	string	Uses `“code”:“description”` format — mandatory	Y

⚠️ Notes & Limits

Notice	Details
Request Limit	This endpoint allows up to 10 patients per request.
Validation	All field-level, boolean, date, and clinic/API checks are applied before processing. Unless otherwise specified objects are required and need to be present.

⛔ Possible Errors

Status Code	Error	Description	Solution
401	Authentication failed	Invalid API key or clinicId combination	Correct combination of ClinicId and API key to be provided
400	Validation failed	First name is required and can only contain letters (A-Z, a-z). No spaces, hyphens, apostrophes, numbers, special, binary, or SQL injection characters allowed.	First name cannot be empty. Provide name satisfying the conditions
400	Validation failed	Last name is required and can only contain letters (A-Z, a-z). No spaces, hyphens, apostrophes, numbers, special, binary, or SQL injection characters allowed.	Last Name cannot be empty. Provide name satisfying the conditions
400	Validation failed	Date of Birth is required, must be in YYYY-MM-DD format, year must be after 1900, and age must be 18 or older	DOB should be in proper format.
400	Validation failed	gender is required and must be one of ‘M’, ‘F’, or ‘O’	Provide proper Gender
400	Validation failed	email must be a valid, email address and only contain letters, numbers, @, and . (no multiple consecutive dots or more than one @ symbol)
400	Validation failed	phone must be 10 digits, optionally prefixed by +1, and contain only numbers
400	Validation failed	primaryLanguage must be a supported language code (EN, ES, FR, DE, ZH, HI)
400	Validation failed	heightInches must be > 1 and < 210
400	Validation failed	weightPounds must be > 1 and < 600
400	Validation failed	address.address1 isrequired, must not contain ‘P.O Box’, ‘PO Box’, or ‘Post Office Box’, cannot have special, binary, or SQL injection characters, and must not contain script injection
400	Validation failed	address.zipCode must be exactly 5 digits or 9 digits in format 12345-1234
400	Validation failed	identity.driverLicenseState is required when driverLicenseNumber is present
400	Validation failed	identity must have either driverLicenseNumber or socialSecurityNumber present and not null
400	Validation failed	socialSecurityNumber must be in the format NNN-NN-NNNN (9 digits, no letters)
400	Bad Request	Invalid allergies format. Expected “CODE:DESCRIPTION	Allergy format should be 00000: None or 00000xxxxx: Description

POST

patients

create

curl --request POST \
  --url https://apidev.epiqconnect.com/patients/create \
  --header 'Content-Type: application/json' \
  --header 'clinicId: <clinicid>' \
  --header 'x-api-key: <x-api-key>' \
  --data @- <<EOF
{
  "patient": {
    "ext_userid": "john-doe-123",
    "firstName": "John",
    "lastName": "O'Connor",
    "middleName": "A",
    "dateOfBirth": "1990-01-01",
    "gender": "M",
    "email": "john.doe@example.com",
    "phone": "+11234567890",
    "primaryLanguage": "EN",
    "heightInches": 72,
    "weightPounds": 180,
    "isSmoker": false,
    "isDiabetic": false,
    "isPregnant": false,
    "address": {
      "address1": "123 Main St",
      "address2": "Apt 101",
      "city": "Dallas",
      "state": "TX",
      "zipCode": "75201-4456",
      "country": "US"
    },
    "identity": {
      "driverLicenseNumber": "D1234567",
      "driverLicenseState": "TX",
      "socialSecurityNumber": "123-45-6789"
    },
    "consents": {
      "sms": true,
      "marketingOptOut": false,
      "thirdPartyOptOut": true
    },
    "riskFactors": {
      "allergies": "peanuts, shellfish",
      "conditions": "asthma, hypertension",
      "medications": "albuterol"
    }
  }
}
EOF

{
  "success": [
    {
      "patientId": "5f020139-130b-4ce5-b3e6-8fec2c1c4c30",
      "ext_userid": "Carl-doe-123",
      "username": "Carl-doe-123",
      "fName": "CARL",
      "lName": "DOE",
      "email": "CARL.DOE@EXAMPLE.COM",
      "phone": "1234567890",
      "userType": "patient",
      "dob": "1990-01-01",
      "gender": "M",
      "statusCode": 201,
      "message": "Patient created successfully",
      "createdAt": "2025-10-13T13:56:05.974Z",
      "updatedAt": "2025-10-13T13:56:05.974Z",
      "clinicId": "3b47a23f-9080-4a2e-a4fa-654d9aa76e80",
      "patient": {
        "patientId": "93411",
        "allergies": "PEANUTS, SHELLFISH",
        "currentMedication": "ALBUTEROL",
        "diagnosis": "ASTHMA, HYPERTENSION",
        "dlState": "TX",
        "dlNumber": "D1234567"
      }
    }
  ],
  "errors": []
}

Headers

clinicId

string

required

Clinic ID for authentication

x-api-key

string

required

Client API key for authentication

Body

application/json

patient

object

required

Array of patients to create

Show child attributes

patient.firstName

string

required

First name of the patient.

Example:

"John"

patient.lastName

string

required

Last name of the patient.

Example:

"Doe"

patient.dateOfBirth

string

required

Date of birth in YYYY-MM-DD format. Year >= 1900 and age >= 18.

Example:

"1990-01-01"

patient.gender

string

required

Gender of the patient. M (male), F (female), O (other).

Example:

"M"

patient.email

string

required

Email address of the patient.

Example:

"john.doe@example.com"

patient.phone

string

required

Phone number of the patient (10 digits).

Example:

"1234567890"

patient.address

object

required

Patient address information

Show child attributes

patient.address.address1

string

required

First line of the address.

Example:

"465 W President George Bush Hwy"

patient.address.address2

string

required

Second line of the address.

Example:

"Suite 240"

patient.address.city

string

required

City.

Example:

"Richardson"

patient.address.state

string

required

State.

Example:

"TX"

patient.address.zipCode

string

required

Zip code.

Example:

"75080"

patient.address.country

string

required

Country.

Example:

"US"

patient.clinicId

string

Clinic ID. Either clinicId or pcn must be provided.

Example:

"clinic-id-123"

patient.pcn

string

PCN. Either clinicId or pcn must be provided.

Example:

"000038"

patient.ext_userid

string

External user ID (optional).

Example:

"external-123"

patient.middleName

string

Middle name of the patient (optional).

Example:

"A"

patient.heightInches

number

Height in inches (optional).

Example:

72

patient.weightPounds

number

Weight in pounds (optional).

Example:

180

patient.primaryLanguage

string

Primary language code (EN, ES, FR, DE, ZH, HI).

Example:

"EN"

patient.isDiabetic

boolean

Is the patient diabetic? (optional)

Example:

false

patient.isPregnant

boolean

Is the patient pregnant? (optional)

Example:

false

patient.riskFactors

object

Patient risk factors including allergies, conditions, and medications

Show child attributes

patient.riskFactors.allergies

string

required

Example:

"2775:Penicillin G Benzathine"

patient.riskFactors.conditions

string

Example:

"asthma, hypertension"

patient.riskFactors.medications

string

Example:

"albuterol, lisinopril"

patient.identity

object

Patient identity information

Show child attributes

patient.identity.driverLicenseNumber

object

Driver license number (optional). If entered, max 20 chars, alphanumeric only.

Example:

"D1234567"

patient.identity.driverLicenseState

object

Driver license state (US state code). Required if driverLicenseNumber is provided.

Example:

"TX"

Social Security Number (optional)

Example:

"123-45-6789"

patient.consents

object

Patient consent settings

Show child attributes

patient.consents.sms

object

SMS consent for notifications. Defaults to true if not provided.

Example:

true

patient.consents.marketingOptOut

object

Marketing opt-out flag. Defaults to false if not provided.

Example:

false

patient.consents.thirdPartyOptOut

object

Third-party opt-out flag. Defaults to true if not provided.

Example:

false

patient.isSmoker

boolean

Is the patient a smoker? (optional)

Example:

false

Response

Patients created successfully

Get patient by ID, apiKey, clinicId or pcnRetrieves a patient record by its unique ID, apiKey, clinicId or PCN. All parameters are accepted in JSON body.

⌘I

curl --request POST \
  --url https://apidev.epiqconnect.com/patients/create \
  --header 'Content-Type: application/json' \
  --header 'clinicId: <clinicid>' \
  --header 'x-api-key: <x-api-key>' \
  --data @- <<EOF
{
  "patient": {
    "ext_userid": "john-doe-123",
    "firstName": "John",
    "lastName": "O'Connor",
    "middleName": "A",
    "dateOfBirth": "1990-01-01",
    "gender": "M",
    "email": "john.doe@example.com",
    "phone": "+11234567890",
    "primaryLanguage": "EN",
    "heightInches": 72,
    "weightPounds": 180,
    "isSmoker": false,
    "isDiabetic": false,
    "isPregnant": false,
    "address": {
      "address1": "123 Main St",
      "address2": "Apt 101",
      "city": "Dallas",
      "state": "TX",
      "zipCode": "75201-4456",
      "country": "US"
    },
    "identity": {
      "driverLicenseNumber": "D1234567",
      "driverLicenseState": "TX",
      "socialSecurityNumber": "123-45-6789"
    },
    "consents": {
      "sms": true,
      "marketingOptOut": false,
      "thirdPartyOptOut": true
    },
    "riskFactors": {
      "allergies": "peanuts, shellfish",
      "conditions": "asthma, hypertension",
      "medications": "albuterol"
    }
  }
}
EOF

{
  "success": [
    {
      "patientId": "5f020139-130b-4ce5-b3e6-8fec2c1c4c30",
      "ext_userid": "Carl-doe-123",
      "username": "Carl-doe-123",
      "fName": "CARL",
      "lName": "DOE",
      "email": "CARL.DOE@EXAMPLE.COM",
      "phone": "1234567890",
      "userType": "patient",
      "dob": "1990-01-01",
      "gender": "M",
      "statusCode": 201,
      "message": "Patient created successfully",
      "createdAt": "2025-10-13T13:56:05.974Z",
      "updatedAt": "2025-10-13T13:56:05.974Z",
      "clinicId": "3b47a23f-9080-4a2e-a4fa-654d9aa76e80",
      "patient": {
        "patientId": "93411",
        "allergies": "PEANUTS, SHELLFISH",
        "currentMedication": "ALBUTEROL",
        "diagnosis": "ASTHMA, HYPERTENSION",
        "dlState": "TX",
        "dlNumber": "D1234567"
      }
    }
  ],
  "errors": []
}

Overview

Patients

Prescribers

Prescriptions

Create Patient for clinic

🛡️ Security

Headers

🩺 Demographics

Patient Info

📞 Contact & Address

Contact

Address

🆔 Identity

Identification

✍️ Consents

🧬 Risk Factors [allergies, conditions, medications]

Risk Factors

⚠️ Notes & Limits

⛔ Possible Errors

Headers

Body

Response