Patient

Welkin provides a comprehensive API to interact with patient data. This includes operations such as listing all patients, filtering patients by email address, creating new patients, and updating existing patient data.

The endpoint for interacting with patients is as follows:

URL Structure: https://api.live.welkincloud.io/{tenant}/{environment}/patients

In our demonstration context, the URL would be https://api.live.welkincloud.io/gh/sb-demo/patients

The patient collection API provides several functionalities:

1. List Patients: Allows retrieval of a list of all patients in the specified Environment of the Organization. The returned list can be sorted based on the required parameters.
2. Filter Patients: This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.
3. Create a New Patient: This operation allows users to create a new patient in the specified Environment.

Current supported timezones to be used in patient creation:

US/Eastern, US/Central, US/Mountain, US/Pacific, US/Alaska, US/Arizona, US/Hawaii, WET, CET, EET, Asia/Dubai, Asia/Singapore, Australia/Perth, Australia/Darwin, Australia/Brisbane, Australia/Adelaide, Australia/Broken_Hill, Antarctica/Casey, Australia/Hobart, Australia/Sydney, Australia/Lord_Howe

Find a Patient

get

Welkin API provides a convenient way to find a patient by using search filters. You can use individual parameters or the search parameter to perform the search.

The search parameter can search for the following values:

• string from FIRST_NAME + MIDLE_NAME + LAST_NAME
• PHONE
• SECONDARY_PHONE
• EMAIL
• SECONDARY_EMAIL
• MRN
• NRIC
• ACCESS_CODE

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

Query parameters

sizeinteger · min: 1 · max: 1000Optional

Number of results per page

Default: 20

sortstringOptional

Sort field and direction, e.g. lastName,asc or createdAt,desc

searchstringOptional

A list of fields available for searching using this parameter can be found on the Overview tab.

Example: Test Patient

emailstringOptionalExample: [e-mail]

mrnstringOptionalExample: R7FQXE

birthDatestring · date-timeOptionalExample: 2019-08-27T00:00:00.000Z

withoutRegionbooleanOptional

true/false

Example: true

withoutTerritorybooleanOptional

true/false

Example: true

Responses

200

Paginated list of patients

application/json

Standard paginated response wrapper.

totalElementsintegerOptional

Total number of matching records

totalPagesintegerOptional

Total number of pages

lastbooleanOptional

firstbooleanOptional

numberintegerOptional

Current page number (zero-based)

sizeintegerOptional

Page size

numberOfElementsintegerOptional

Number of elements on the current page

emptybooleanOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

get/{tenantName}/{instanceName}/patients

GET /{tenantName}/{instanceName}/patients HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "text",
      "mrn": "text",
      "nric": "text",
      "accessCode": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "createdByName": "text",
      "updatedByName": "text",
      "firstName": "text",
      "lastName": "text",
      "middleName": "text",
      "birthDate": "2026-01-01T00:00:00.000Z",
      "gender": "MALE",
      "maritalStatus": "A",
      "primaryLanguage": "ENGLISH",
      "secondaryLanguage": "ENGLISH",
      "email": "[e-mail]",
      "secondaryEmail": "[e-mail]",
      "phone": "text",
      "phoneLabel": "text",
      "primaryPhoneCapabilities": [
        "VOICE_CALL"
      ],
      "secondaryPhone": "text",
      "secondaryPhoneLabel": "text",
      "secondaryPhoneCapabilities": [
        "VOICE_CALL"
      ],
      "preferableInstancePhoneId": "123e4567-e89b-12d3-a456-426614174000",
      "country": "text",
      "state": "text",
      "city": "text",
      "zip": "text",
      "addressLine1": "text",
      "addressLine2": "text",
      "timezone": "text",
      "patientType": "ADULT",
      "notes": "text",
      "careTeamMembers": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "pointOfContact": true
        }
      ],
      "patientPrograms": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "createdByName": "text",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedByName": "text",
          "updatedAt": "2026-01-01T00:00:00.000Z",
          "programName": "text",
          "programTitle": "text",
          "programDescription": "text",
          "assigned": true,
          "patientId": "123e4567-e89b-12d3-a456-426614174000",
          "currentPhase": {
            "timestamp": "2026-01-01T00:00:00.000Z",
            "createdBy": "123e4567-e89b-12d3-a456-426614174000",
            "createdByName": "text",
            "name": "text",
            "title": "text",
            "description": "text",
            "currentVersion": "text",
            "deleted": true
          },
          "status": "NOT_STARTED",
          "compatibleWithCurrentVersion": true,
          "pathHistory": [
            {
              "timestamp": "2026-01-01T00:00:00.000Z",
              "createdBy": "123e4567-e89b-12d3-a456-426614174000",
              "createdByName": "text",
              "name": "text",
              "title": "text",
              "description": "text",
              "currentVersion": "text",
              "deleted": true
            }
          ]
        }
      ],
      "careTeam": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "username": "text",
          "firstName": "text",
          "lastName": "text",
          "email": "[e-mail]",
          "roles": [
            {
              "name": "text",
              "primaryRole": true,
              "description": "text",
              "instanceId": "123e4567-e89b-12d3-a456-426614174000"
            }
          ],
          "pointOfContact": true,
          "enabled": true
        }
      ],
      "territorialTeam": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "username": "text",
          "firstName": "text",
          "lastName": "text",
          "email": "[e-mail]",
          "roles": [
            {
              "name": "text",
              "primaryRole": true,
              "description": "text",
              "instanceId": "123e4567-e89b-12d3-a456-426614174000"
            }
          ],
          "pointOfContact": true,
          "enabled": true
        }
      ],
      "cadence": [
        {
          "schedules": [
            {
              "hour": 1,
              "minute": 1,
              "days": [
                "MONDAY"
              ],
              "weekNumbers": [
                1
              ]
            }
          ],
          "priority": "LOW"
        }
      ],
      "patientRegion": "text",
      "patientRegionTitle": "text",
      "patientTerritory": "text",
      "pointOfContact": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "text",
        "firstName": "text",
        "lastName": "text",
        "email": "[e-mail]",
        "roles": [
          {
            "name": "text",
            "primaryRole": true,
            "description": "text",
            "instanceId": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "pointOfContact": true,
        "enabled": true
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "pageSize": 1,
    "pageNumber": 1,
    "offset": 1,
    "unpaged": true,
    "paged": true
  },
  "totalElements": 1,
  "totalPages": 1,
  "last": true,
  "first": true,
  "number": 1,
  "size": 1,
  "numberOfElements": 1,
  "empty": true,
  "sort": {
    "sorted": true,
    "unsorted": true,
    "empty": true
  }
}

Create a Patient

post

Creating a new Patient in Welkin involves making a POST request to the Patient Collection resource.

HTTP URL: https://api.live.welkincloud.io/gh/sb-demo/patients

HTTP Response Codes:

• 201: Successfully created a new patient
• 400: Bad request - the request could not be understood or was missing required parameters
• 500: Internal server error - something went wrong on the server

Notes:

"firstName" and "lastName" are required fields. Another fields depends on Designer settings.

1. patientTerritories: This field should contain valid territories that have been previously set up in the Designer. If you don't have the territories information at the time of creating a patient, you can omit this field and update it later.
2. careTeam (careTeamMembers is deprecated, use only careTeam to update): All members listed in the careTeam must be valid users. One member should be designated as the point of contact by setting "pointOfContact": True. If no one is explicitly marked, the system will automatically assign the first user listed in the careTeam as the point of contact. If you don't have the care team information at the time of creating a patient, you can omit this field and update it later.
3. phone: when working with patients and fields such as phone, phone must be specified in the international format, E.164 format, without zero example for Australia: [phone] correct phone format [phone] incorrect phone format

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

Body

firstNamestringRequiredExample: Jane

lastNamestringRequiredExample: Doe

emailstring · emailOptional

phonestringOptional

E.164 format, e.g. [phone]

Example: [phone]

birthDatestring · date-timeOptional

timezonestringOptionalExample: America/New_York

externalGuidstring · uuidOptional

countrystringOptional

statestringOptional

citystringOptional

zipstringOptional

addressLine1stringOptional

addressLine2stringOptional

genderstring · enumOptionalPossible values:

maritalStatusstring · enumOptional

A = Annulled, D = Divorced, I = Interlocutory, L = Legally Separated, M = Married, P = Polygamous, S = Never Married, T = Domestic partner, U = Unmarried, W = Widowed, UKN = Unknown

Possible values:

primaryLanguagestring · enumOptionalPossible values:

secondaryLanguagestring · enumOptionalPossible values:

secondaryEmailstring · emailOptional

phoneLabelstringOptional

secondaryPhonestringOptional

E.164 format

secondaryPhoneLabelstringOptional

patientTypestring · enumOptionalPossible values:

notesstringOptional

patientRegionstringOptional

patientTerritorystringOptional

Responses

201

Patient created

application/json

Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.

idstring · uuidOptional

externalGuidstring · uuid · nullableOptional

externalIdstring · nullableOptional

mrnstring · nullableOptional

nricstring · nullableOptional

accessCodestring · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

createdByNamestringOptional

updatedByNamestringOptional

firstNamestringOptional

lastNamestringOptional

middleNamestring · nullableOptional

birthDatestring · date-time · nullableOptional

genderstring · enumOptionalPossible values:

maritalStatusstring · enumOptional

A = Annulled, D = Divorced, I = Interlocutory, L = Legally Separated, M = Married, P = Polygamous, S = Never Married, T = Domestic partner, U = Unmarried, W = Widowed, UKN = Unknown

Possible values:

primaryLanguagestring · enumOptionalPossible values:

secondaryLanguagestring · enumOptionalPossible values:

emailstring · email · nullableOptional

secondaryEmailstring · email · nullableOptional

phonestring · nullableOptional

phoneLabelstring · nullableOptional

secondaryPhonestring · nullableOptional

secondaryPhoneLabelstring · nullableOptional

preferableInstancePhoneIdstring · uuid · nullableOptional

countrystring · nullableOptional

statestring · nullableOptional

citystring · nullableOptional

zipstring · nullableOptional

addressLine1string · nullableOptional

addressLine2string · nullableOptional

timezonestring · nullableOptional

patientTypestring · enumOptionalPossible values:

notesstring · nullableOptional

patientRegionstring · nullableOptional

patientRegionTitlestring · nullableRead-onlyOptional

patientTerritorystring · nullableOptional

Other propertiesanyOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

post/{tenantName}/{instanceName}/patients

POST /{tenantName}/{instanceName}/patients HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 844

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[e-mail]",
  "phone": "[phone]",
  "birthDate": "2026-01-01T00:00:00.000Z",
  "timezone": "America/New_York",
  "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
  "country": "text",
  "state": "text",
  "city": "text",
  "zip": "text",
  "addressLine1": "text",
  "addressLine2": "text",
  "patientTerritories": [
    {
      "name": "text",
      "territories": [
        "text"
      ]
    }
  ],
  "careTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "pointOfContact": true
    }
  ],
  "gender": "MALE",
  "maritalStatus": "A",
  "primaryLanguage": "ENGLISH",
  "secondaryLanguage": "ENGLISH",
  "secondaryEmail": "[e-mail]",
  "phoneLabel": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "patientType": "ADULT",
  "notes": "text",
  "cadence": [
    {
      "schedules": [
        {
          "hour": 1,
          "minute": 1,
          "days": [
            "MONDAY"
          ],
          "weekNumbers": [
            1
          ]
        }
      ],
      "priority": "LOW"
    }
  ],
  "patientRegion": "text",
  "patientTerritory": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "mrn": "text",
  "nric": "text",
  "accessCode": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdByName": "text",
  "updatedByName": "text",
  "firstName": "text",
  "lastName": "text",
  "middleName": "text",
  "birthDate": "2026-01-01T00:00:00.000Z",
  "gender": "MALE",
  "maritalStatus": "A",
  "primaryLanguage": "ENGLISH",
  "secondaryLanguage": "ENGLISH",
  "email": "[e-mail]",
  "secondaryEmail": "[e-mail]",
  "phone": "text",
  "phoneLabel": "text",
  "primaryPhoneCapabilities": [
    "VOICE_CALL"
  ],
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhoneCapabilities": [
    "VOICE_CALL"
  ],
  "preferableInstancePhoneId": "123e4567-e89b-12d3-a456-426614174000",
  "country": "text",
  "state": "text",
  "city": "text",
  "zip": "text",
  "addressLine1": "text",
  "addressLine2": "text",
  "timezone": "text",
  "patientType": "ADULT",
  "notes": "text",
  "careTeamMembers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "pointOfContact": true
    }
  ],
  "patientPrograms": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedByName": "text",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "programName": "text",
      "programTitle": "text",
      "programDescription": "text",
      "assigned": true,
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "currentPhase": {
        "timestamp": "2026-01-01T00:00:00.000Z",
        "createdBy": "123e4567-e89b-12d3-a456-426614174000",
        "createdByName": "text",
        "name": "text",
        "title": "text",
        "description": "text",
        "currentVersion": "text",
        "deleted": true
      },
      "status": "NOT_STARTED",
      "compatibleWithCurrentVersion": true,
      "pathHistory": [
        {
          "timestamp": "2026-01-01T00:00:00.000Z",
          "createdBy": "123e4567-e89b-12d3-a456-426614174000",
          "createdByName": "text",
          "name": "text",
          "title": "text",
          "description": "text",
          "currentVersion": "text",
          "deleted": true
        }
      ]
    }
  ],
  "careTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "text",
      "firstName": "text",
      "lastName": "text",
      "email": "[e-mail]",
      "roles": [
        {
          "name": "text",
          "primaryRole": true,
          "description": "text",
          "instanceId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "pointOfContact": true,
      "enabled": true
    }
  ],
  "territorialTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "text",
      "firstName": "text",
      "lastName": "text",
      "email": "[e-mail]",
      "roles": [
        {
          "name": "text",
          "primaryRole": true,
          "description": "text",
          "instanceId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "pointOfContact": true,
      "enabled": true
    }
  ],
  "cadence": [
    {
      "schedules": [
        {
          "hour": 1,
          "minute": 1,
          "days": [
            "MONDAY"
          ],
          "weekNumbers": [
            1
          ]
        }
      ],
      "priority": "LOW"
    }
  ],
  "patientRegion": "text",
  "patientRegionTitle": "text",
  "patientTerritory": "text",
  "pointOfContact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "username": "text",
    "firstName": "text",
    "lastName": "text",
    "email": "[e-mail]",
    "roles": [
      {
        "name": "text",
        "primaryRole": true,
        "description": "text",
        "instanceId": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "pointOfContact": true,
    "enabled": true
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Bulk update for Patients

patch

Note: When updating a patient's record or any other resource using a PATCH request, you only need to include the fields that you wish to modify. Any fields that are not included in the request will retain their existing values in the database.

The query allows you to update patient information in bulk

ids - list of patient IDs for which to apply changes

careTeamAdditions - list of user IDs to be added to the patient care team (new users will be added to the care team and existing users will remain unchanged)

careTeamReplacements - the block allows you to replace one user in the patient care team with a different one

careTeamRemovals - list of user IDs to be removed from the patient care team (specified users will be removed from the care team and others will not be affected)

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

Body

idsstring · uuid[] · min: 1Required

timezonestringOptional

patientRegionstringOptional

patientTerritorystringOptional

careTeamAdditionsstring · uuid[]Optional

careTeamRemovalsstring · uuid[]Optional

Responses

200

Updated patients

application/json

Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.

idstring · uuidOptional

externalGuidstring · uuid · nullableOptional

externalIdstring · nullableOptional

mrnstring · nullableOptional

nricstring · nullableOptional

accessCodestring · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

createdByNamestringOptional

updatedByNamestringOptional

firstNamestringOptional

lastNamestringOptional

middleNamestring · nullableOptional

birthDatestring · date-time · nullableOptional

genderstring · enumOptionalPossible values:

maritalStatusstring · enumOptional

A = Annulled, D = Divorced, I = Interlocutory, L = Legally Separated, M = Married, P = Polygamous, S = Never Married, T = Domestic partner, U = Unmarried, W = Widowed, UKN = Unknown

Possible values:

primaryLanguagestring · enumOptionalPossible values:

secondaryLanguagestring · enumOptionalPossible values:

emailstring · email · nullableOptional

secondaryEmailstring · email · nullableOptional

phonestring · nullableOptional

phoneLabelstring · nullableOptional

secondaryPhonestring · nullableOptional

secondaryPhoneLabelstring · nullableOptional

preferableInstancePhoneIdstring · uuid · nullableOptional

countrystring · nullableOptional

statestring · nullableOptional

citystring · nullableOptional

zipstring · nullableOptional

addressLine1string · nullableOptional

addressLine2string · nullableOptional

timezonestring · nullableOptional

patientTypestring · enumOptionalPossible values:

notesstring · nullableOptional

patientRegionstring · nullableOptional

patientRegionTitlestring · nullableRead-onlyOptional

patientTerritorystring · nullableOptional

Other propertiesanyOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

patch/{tenantName}/{instanceName}/patients

PATCH /{tenantName}/{instanceName}/patients HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 599

{
  "ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "timezone": "text",
  "patientTerritories": [
    {
      "name": "text",
      "territories": [
        "text"
      ]
    }
  ],
  "patientRegion": "text",
  "patientTerritory": "text",
  "careTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "pointOfContact": true
    }
  ],
  "cadence": [
    {
      "schedules": [
        {
          "hour": 1,
          "minute": 1,
          "days": [
            "MONDAY"
          ],
          "weekNumbers": [
            1
          ]
        }
      ],
      "priority": "LOW"
    }
  ],
  "careTeamAdditions": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "careTeamReplacements": [
    {
      "from": "123e4567-e89b-12d3-a456-426614174000",
      "to": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "careTeamRemovals": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "text",
    "mrn": "text",
    "nric": "text",
    "accessCode": "text",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "createdByName": "text",
    "updatedByName": "text",
    "firstName": "text",
    "lastName": "text",
    "middleName": "text",
    "birthDate": "2026-01-01T00:00:00.000Z",
    "gender": "MALE",
    "maritalStatus": "A",
    "primaryLanguage": "ENGLISH",
    "secondaryLanguage": "ENGLISH",
    "email": "[e-mail]",
    "secondaryEmail": "[e-mail]",
    "phone": "text",
    "phoneLabel": "text",
    "primaryPhoneCapabilities": [
      "VOICE_CALL"
    ],
    "secondaryPhone": "text",
    "secondaryPhoneLabel": "text",
    "secondaryPhoneCapabilities": [
      "VOICE_CALL"
    ],
    "preferableInstancePhoneId": "123e4567-e89b-12d3-a456-426614174000",
    "country": "text",
    "state": "text",
    "city": "text",
    "zip": "text",
    "addressLine1": "text",
    "addressLine2": "text",
    "timezone": "text",
    "patientType": "ADULT",
    "notes": "text",
    "careTeamMembers": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "pointOfContact": true
      }
    ],
    "patientPrograms": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "createdByName": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedByName": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z",
        "programName": "text",
        "programTitle": "text",
        "programDescription": "text",
        "assigned": true,
        "patientId": "123e4567-e89b-12d3-a456-426614174000",
        "currentPhase": {
          "timestamp": "2026-01-01T00:00:00.000Z",
          "createdBy": "123e4567-e89b-12d3-a456-426614174000",
          "createdByName": "text",
          "name": "text",
          "title": "text",
          "description": "text",
          "currentVersion": "text",
          "deleted": true
        },
        "status": "NOT_STARTED",
        "compatibleWithCurrentVersion": true,
        "pathHistory": [
          {
            "timestamp": "2026-01-01T00:00:00.000Z",
            "createdBy": "123e4567-e89b-12d3-a456-426614174000",
            "createdByName": "text",
            "name": "text",
            "title": "text",
            "description": "text",
            "currentVersion": "text",
            "deleted": true
          }
        ]
      }
    ],
    "careTeam": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "text",
        "firstName": "text",
        "lastName": "text",
        "email": "[e-mail]",
        "roles": [
          {
            "name": "text",
            "primaryRole": true,
            "description": "text",
            "instanceId": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "pointOfContact": true,
        "enabled": true
      }
    ],
    "territorialTeam": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "text",
        "firstName": "text",
        "lastName": "text",
        "email": "[e-mail]",
        "roles": [
          {
            "name": "text",
            "primaryRole": true,
            "description": "text",
            "instanceId": "123e4567-e89b-12d3-a456-426614174000"
          }
        ],
        "pointOfContact": true,
        "enabled": true
      }
    ],
    "cadence": [
      {
        "schedules": [
          {
            "hour": 1,
            "minute": 1,
            "days": [
              "MONDAY"
            ],
            "weekNumbers": [
              1
            ]
          }
        ],
        "priority": "LOW"
      }
    ],
    "patientRegion": "text",
    "patientRegionTitle": "text",
    "patientTerritory": "text",
    "pointOfContact": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "text",
      "firstName": "text",
      "lastName": "text",
      "email": "[e-mail]",
      "roles": [
        {
          "name": "text",
          "primaryRole": true,
          "description": "text",
          "instanceId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "pointOfContact": true,
      "enabled": true
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
]

Get a specific Patient By ID, externalID, externalGUID, MRN

get

You can retrieve a specific patient's details by using a known identifier such as ID, external id (EID), external guid (EGUID), or medical record number (MRN).

HTTP URL: https://api.live.welkincloud.io/gh/sb-demo/patients/{identifier}?type={type}

HTTP Response Codes:

• 200: Successfully retrieved the patient's details
• 400: Bad request - the request could not be understood or was missing required parameters
• 500: Internal server error - something went wrong on the server

Here are a few examples illustrating how you can use different identifiers to retrieve a patient:

1. https://api.live.welkincloud.io/gh/sb-demo/patients/someId?type=EID
2. https://api.live.welkincloud.io/gh/sb-demo/patients/123e4567-e89b-12d3-a456-426655440000?type=EGUID
3. https://api.live.welkincloud.io/gh/sb-demo/patients/someMRN?type=MRN
4. https://api.live.welkincloud.io/gh/sb-demo/patients/someId?type=EID&expand=true

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Query parameters

typestringOptional

Type of identifier: ID, EID, EGUID, MRN (default ID)

Example: EGUID

expandstringOptional

If true, request will return dto with territorialTeam field (default false)

Body

firstNamestringRequiredExample: Jane

lastNamestringRequiredExample: Doe

emailstring · emailOptional

phonestringOptional

E.164 format, e.g. [phone]

Example: [phone]

birthDatestring · date-timeOptional

timezonestringOptionalExample: America/New_York

externalGuidstring · uuidOptional

countrystringOptional

statestringOptional

citystringOptional

zipstringOptional

addressLine1stringOptional

addressLine2stringOptional

genderstring · enumOptionalPossible values:

maritalStatusstring · enumOptional

A = Annulled, D = Divorced, I = Interlocutory, L = Legally Separated, M = Married, P = Polygamous, S = Never Married, T = Domestic partner, U = Unmarried, W = Widowed, UKN = Unknown

Possible values:

primaryLanguagestring · enumOptionalPossible values:

secondaryLanguagestring · enumOptionalPossible values:

secondaryEmailstring · emailOptional

phoneLabelstringOptional

secondaryPhonestringOptional

E.164 format

secondaryPhoneLabelstringOptional

patientTypestring · enumOptionalPossible values:

notesstringOptional

patientRegionstringOptional

patientTerritorystringOptional

Responses

200

Patient record

application/json

Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.

idstring · uuidOptional

externalGuidstring · uuid · nullableOptional

externalIdstring · nullableOptional

mrnstring · nullableOptional

nricstring · nullableOptional

accessCodestring · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

createdByNamestringOptional

updatedByNamestringOptional

firstNamestringOptional

lastNamestringOptional

middleNamestring · nullableOptional

birthDatestring · date-time · nullableOptional

genderstring · enumOptionalPossible values:

maritalStatusstring · enumOptional

A = Annulled, D = Divorced, I = Interlocutory, L = Legally Separated, M = Married, P = Polygamous, S = Never Married, T = Domestic partner, U = Unmarried, W = Widowed, UKN = Unknown

Possible values:

primaryLanguagestring · enumOptionalPossible values:

secondaryLanguagestring · enumOptionalPossible values:

emailstring · email · nullableOptional

secondaryEmailstring · email · nullableOptional

phonestring · nullableOptional

phoneLabelstring · nullableOptional

secondaryPhonestring · nullableOptional

secondaryPhoneLabelstring · nullableOptional

preferableInstancePhoneIdstring · uuid · nullableOptional

countrystring · nullableOptional

statestring · nullableOptional

citystring · nullableOptional

zipstring · nullableOptional

addressLine1string · nullableOptional

addressLine2string · nullableOptional

timezonestring · nullableOptional

patientTypestring · enumOptionalPossible values:

notesstring · nullableOptional

patientRegionstring · nullableOptional

patientRegionTitlestring · nullableRead-onlyOptional

patientTerritorystring · nullableOptional

Other propertiesanyOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}

GET /{tenantName}/{instanceName}/patients/{patientId} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 844

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[e-mail]",
  "phone": "[phone]",
  "birthDate": "2026-01-01T00:00:00.000Z",
  "timezone": "America/New_York",
  "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
  "country": "text",
  "state": "text",
  "city": "text",
  "zip": "text",
  "addressLine1": "text",
  "addressLine2": "text",
  "patientTerritories": [
    {
      "name": "text",
      "territories": [
        "text"
      ]
    }
  ],
  "careTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "pointOfContact": true
    }
  ],
  "gender": "MALE",
  "maritalStatus": "A",
  "primaryLanguage": "ENGLISH",
  "secondaryLanguage": "ENGLISH",
  "secondaryEmail": "[e-mail]",
  "phoneLabel": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "patientType": "ADULT",
  "notes": "text",
  "cadence": [
    {
      "schedules": [
        {
          "hour": 1,
          "minute": 1,
          "days": [
            "MONDAY"
          ],
          "weekNumbers": [
            1
          ]
        }
      ],
      "priority": "LOW"
    }
  ],
  "patientRegion": "text",
  "patientTerritory": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "mrn": "text",
  "nric": "text",
  "accessCode": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdByName": "text",
  "updatedByName": "text",
  "firstName": "text",
  "lastName": "text",
  "middleName": "text",
  "birthDate": "2026-01-01T00:00:00.000Z",
  "gender": "MALE",
  "maritalStatus": "A",
  "primaryLanguage": "ENGLISH",
  "secondaryLanguage": "ENGLISH",
  "email": "[e-mail]",
  "secondaryEmail": "[e-mail]",
  "phone": "text",
  "phoneLabel": "text",
  "primaryPhoneCapabilities": [
    "VOICE_CALL"
  ],
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhoneCapabilities": [
    "VOICE_CALL"
  ],
  "preferableInstancePhoneId": "123e4567-e89b-12d3-a456-426614174000",
  "country": "text",
  "state": "text",
  "city": "text",
  "zip": "text",
  "addressLine1": "text",
  "addressLine2": "text",
  "timezone": "text",
  "patientType": "ADULT",
  "notes": "text",
  "careTeamMembers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "pointOfContact": true
    }
  ],
  "patientPrograms": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedByName": "text",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "programName": "text",
      "programTitle": "text",
      "programDescription": "text",
      "assigned": true,
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "currentPhase": {
        "timestamp": "2026-01-01T00:00:00.000Z",
        "createdBy": "123e4567-e89b-12d3-a456-426614174000",
        "createdByName": "text",
        "name": "text",
        "title": "text",
        "description": "text",
        "currentVersion": "text",
        "deleted": true
      },
      "status": "NOT_STARTED",
      "compatibleWithCurrentVersion": true,
      "pathHistory": [
        {
          "timestamp": "2026-01-01T00:00:00.000Z",
          "createdBy": "123e4567-e89b-12d3-a456-426614174000",
          "createdByName": "text",
          "name": "text",
          "title": "text",
          "description": "text",
          "currentVersion": "text",
          "deleted": true
        }
      ]
    }
  ],
  "careTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "text",
      "firstName": "text",
      "lastName": "text",
      "email": "[e-mail]",
      "roles": [
        {
          "name": "text",
          "primaryRole": true,
          "description": "text",
          "instanceId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "pointOfContact": true,
      "enabled": true
    }
  ],
  "territorialTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "text",
      "firstName": "text",
      "lastName": "text",
      "email": "[e-mail]",
      "roles": [
        {
          "name": "text",
          "primaryRole": true,
          "description": "text",
          "instanceId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "pointOfContact": true,
      "enabled": true
    }
  ],
  "cadence": [
    {
      "schedules": [
        {
          "hour": 1,
          "minute": 1,
          "days": [
            "MONDAY"
          ],
          "weekNumbers": [
            1
          ]
        }
      ],
      "priority": "LOW"
    }
  ],
  "patientRegion": "text",
  "patientRegionTitle": "text",
  "patientTerritory": "text",
  "pointOfContact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "username": "text",
    "firstName": "text",
    "lastName": "text",
    "email": "[e-mail]",
    "roles": [
      {
        "name": "text",
        "primaryRole": true,
        "description": "text",
        "instanceId": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "pointOfContact": true,
    "enabled": true
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Delete Patient by ID

delete

Description: This API endpoint allows you to delete a specific patient record within the context of the specified tenant and instance. It provides a way to remove patient data from the system permanently.

Parameters:

• url: The base URL of the API.
• tenantName: The name or identifier of the tenant within which the patient record exists.
• instanceName: The name or identifier of the specific instance under the given tenant.
• patientId: The unique identifier of the patient record you want to delete.

Request Headers: No special headers are required for this request.

Request Body: This endpoint does not require a request body.

Response:

• 204 No Content: The request was successful, and the patient record has been deleted. No response body will be returned.
• 404 Not Found: The requested patient or resource was not found. An error message or response body may provide additional information.

Authorization: Ensure that the caller of this endpoint has the necessary permissions to delete patient records. Implement appropriate authentication and authorization mechanisms.

Usage: Before using this endpoint, ensure that you have the correct URL, tenant name, instance name, and patient ID. Make sure to handle responses, especially errors, appropriately in your application.

Notes:

• Deleting a patient record is irreversible, so exercise caution while using this endpoint.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Query parameters

typestringOptional

ID,EGUID

Example: EGUID

Responses

200

Patient deleted

No content

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

delete/{tenantName}/{instanceName}/patients/{patientId}

DELETE /{tenantName}/{instanceName}/patients/{patientId} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a specific Patient By ID

patch

To update a patient by a known ID

1. HTTP Method: PATCH
2. HTTP URL: https://api.live.welkincloud.io/gh/sb-demo/patients/6801d498-26f4-4aee-961b-5daffcf193c8
3. HTTP Response Codes: 200, 400, 404, 500

Note:

• phone: when working with patients and fields such as phone, phone must be specified in the international format, E.164 format, without zero
• careTeamMembers is deprecated, use only careTeam to update

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Body

Partial update — all fields optional. Omitted fields are left unchanged.

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

emailstring · emailOptional

phonestringOptional

E.164 format, e.g. [phone]

Example: [phone]

birthDatestring · date-timeOptional

timezonestringOptionalExample: America/New_York

externalGuidstring · uuidOptional

countrystringOptional

statestringOptional

citystringOptional

zipstringOptional

addressLine1stringOptional

addressLine2stringOptional

genderstring · enumOptionalPossible values:

maritalStatusstring · enumOptional

A = Annulled, D = Divorced, I = Interlocutory, L = Legally Separated, M = Married, P = Polygamous, S = Never Married, T = Domestic partner, U = Unmarried, W = Widowed, UKN = Unknown

Possible values:

primaryLanguagestring · enumOptionalPossible values:

secondaryLanguagestring · enumOptionalPossible values:

secondaryEmailstring · emailOptional

phoneLabelstringOptional

secondaryPhonestringOptional

E.164 format

secondaryPhoneLabelstringOptional

patientTypestring · enumOptionalPossible values:

notesstringOptional

patientRegionstringOptional

patientTerritorystringOptional

Responses

200

Updated patient

application/json

Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.

idstring · uuidOptional

externalGuidstring · uuid · nullableOptional

externalIdstring · nullableOptional

mrnstring · nullableOptional

nricstring · nullableOptional

accessCodestring · nullableOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

createdByNamestringOptional

updatedByNamestringOptional

firstNamestringOptional

lastNamestringOptional

middleNamestring · nullableOptional

birthDatestring · date-time · nullableOptional

genderstring · enumOptionalPossible values:

maritalStatusstring · enumOptional

A = Annulled, D = Divorced, I = Interlocutory, L = Legally Separated, M = Married, P = Polygamous, S = Never Married, T = Domestic partner, U = Unmarried, W = Widowed, UKN = Unknown

Possible values:

primaryLanguagestring · enumOptionalPossible values:

secondaryLanguagestring · enumOptionalPossible values:

emailstring · email · nullableOptional

secondaryEmailstring · email · nullableOptional

phonestring · nullableOptional

phoneLabelstring · nullableOptional

secondaryPhonestring · nullableOptional

secondaryPhoneLabelstring · nullableOptional

preferableInstancePhoneIdstring · uuid · nullableOptional

countrystring · nullableOptional

statestring · nullableOptional

citystring · nullableOptional

zipstring · nullableOptional

addressLine1string · nullableOptional

addressLine2string · nullableOptional

timezonestring · nullableOptional

patientTypestring · enumOptionalPossible values:

notesstring · nullableOptional

patientRegionstring · nullableOptional

patientRegionTitlestring · nullableRead-onlyOptional

patientTerritorystring · nullableOptional

Other propertiesanyOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

patch/{tenantName}/{instanceName}/patients/{patientId}

PATCH /{tenantName}/{instanceName}/patients/{patientId} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 844

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[e-mail]",
  "phone": "[phone]",
  "birthDate": "2026-01-01T00:00:00.000Z",
  "timezone": "America/New_York",
  "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
  "country": "text",
  "state": "text",
  "city": "text",
  "zip": "text",
  "addressLine1": "text",
  "addressLine2": "text",
  "patientTerritories": [
    {
      "name": "text",
      "territories": [
        "text"
      ]
    }
  ],
  "careTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "pointOfContact": true
    }
  ],
  "gender": "MALE",
  "maritalStatus": "A",
  "primaryLanguage": "ENGLISH",
  "secondaryLanguage": "ENGLISH",
  "secondaryEmail": "[e-mail]",
  "phoneLabel": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "patientType": "ADULT",
  "notes": "text",
  "cadence": [
    {
      "schedules": [
        {
          "hour": 1,
          "minute": 1,
          "days": [
            "MONDAY"
          ],
          "weekNumbers": [
            1
          ]
        }
      ],
      "priority": "LOW"
    }
  ],
  "patientRegion": "text",
  "patientTerritory": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalGuid": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "mrn": "text",
  "nric": "text",
  "accessCode": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdByName": "text",
  "updatedByName": "text",
  "firstName": "text",
  "lastName": "text",
  "middleName": "text",
  "birthDate": "2026-01-01T00:00:00.000Z",
  "gender": "MALE",
  "maritalStatus": "A",
  "primaryLanguage": "ENGLISH",
  "secondaryLanguage": "ENGLISH",
  "email": "[e-mail]",
  "secondaryEmail": "[e-mail]",
  "phone": "text",
  "phoneLabel": "text",
  "primaryPhoneCapabilities": [
    "VOICE_CALL"
  ],
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhoneCapabilities": [
    "VOICE_CALL"
  ],
  "preferableInstancePhoneId": "123e4567-e89b-12d3-a456-426614174000",
  "country": "text",
  "state": "text",
  "city": "text",
  "zip": "text",
  "addressLine1": "text",
  "addressLine2": "text",
  "timezone": "text",
  "patientType": "ADULT",
  "notes": "text",
  "careTeamMembers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "pointOfContact": true
    }
  ],
  "patientPrograms": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedByName": "text",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "programName": "text",
      "programTitle": "text",
      "programDescription": "text",
      "assigned": true,
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "currentPhase": {
        "timestamp": "2026-01-01T00:00:00.000Z",
        "createdBy": "123e4567-e89b-12d3-a456-426614174000",
        "createdByName": "text",
        "name": "text",
        "title": "text",
        "description": "text",
        "currentVersion": "text",
        "deleted": true
      },
      "status": "NOT_STARTED",
      "compatibleWithCurrentVersion": true,
      "pathHistory": [
        {
          "timestamp": "2026-01-01T00:00:00.000Z",
          "createdBy": "123e4567-e89b-12d3-a456-426614174000",
          "createdByName": "text",
          "name": "text",
          "title": "text",
          "description": "text",
          "currentVersion": "text",
          "deleted": true
        }
      ]
    }
  ],
  "careTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "text",
      "firstName": "text",
      "lastName": "text",
      "email": "[e-mail]",
      "roles": [
        {
          "name": "text",
          "primaryRole": true,
          "description": "text",
          "instanceId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "pointOfContact": true,
      "enabled": true
    }
  ],
  "territorialTeam": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "text",
      "firstName": "text",
      "lastName": "text",
      "email": "[e-mail]",
      "roles": [
        {
          "name": "text",
          "primaryRole": true,
          "description": "text",
          "instanceId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "pointOfContact": true,
      "enabled": true
    }
  ],
  "cadence": [
    {
      "schedules": [
        {
          "hour": 1,
          "minute": 1,
          "days": [
            "MONDAY"
          ],
          "weekNumbers": [
            1
          ]
        }
      ],
      "priority": "LOW"
    }
  ],
  "patientRegion": "text",
  "patientRegionTitle": "text",
  "patientTerritory": "text",
  "pointOfContact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "username": "text",
    "firstName": "text",
    "lastName": "text",
    "email": "[e-mail]",
    "roles": [
      {
        "name": "text",
        "primaryRole": true,
        "description": "text",
        "instanceId": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "pointOfContact": true,
    "enabled": true
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Find by filters

post

Request to search for patients based on filters. It can accept different parameters:

• timezones
• withoutTimezone
• cadence
• territories
• userRegions
• regions
• withoutRegion
• withoutTerritory
• careTeamOnly
• primaryContact
• careTeamIds
• currentUserId
• birthDate
• programs
• withoutProgram
• phone
• mrn
• nric
• accessCode

You can also pass a "query" parameter and some value - in this case a “global” search will occur across multiple fields (firstName, lastName, mrn, email, secondaryEmail, ...) and also supports partial matches. Example:

"query": "[e-mail]"

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

Body

Filter criteria for finding patients.

searchstring · max: 50Optional

emailstring · emailOptional

mrnstringOptional

birthDatestring · date-timeOptional

withoutRegionbooleanOptional

withoutTerritorybooleanOptional

timezonesstring[]Optional

territoriesstringOptional

careTeamIdsstring · uuid[]Optional

cadencestringOptional

careTeamOnlybooleanOptionalDefault: false

primaryContactbooleanOptionalDefault: false

idsstring · uuid[]Optional

dateStartstring · date-timeOptional

dateEndstring · date-timeOptional

Responses

200

Paginated list of matching patients

application/json

201

Success

No content

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

post/{tenantName}/{instanceName}/by-filter/patients

POST /{tenantName}/{instanceName}/by-filter/patients HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 420

{
  "search": "text",
  "email": "[e-mail]",
  "mrn": "text",
  "birthDate": "2026-01-01T00:00:00.000Z",
  "withoutRegion": true,
  "withoutTerritory": true,
  "timezones": [
    "text"
  ],
  "territories": "text",
  "careTeamIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "cadence": "text",
  "careTeamOnly": false,
  "primaryContact": false,
  "ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "dateStart": "2026-01-01T00:00:00.000Z",
  "dateEnd": "2026-01-01T00:00:00.000Z"
}

No content