> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/api-reference/patient.md). # 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 > 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 ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Patient","description":"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.\n\nThe endpoint for interacting with patients is as follows:\n\nURL Structure: `https://api.live.welkincloud.io/{tenant}/{environment}/patients`\n\nIn our demonstration context, the URL would be `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\nThe patient collection API provides several functionalities:\n\n1. **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.\n2. **Filter Patients:** This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.\n3. **Create a New Patient:** This operation allows users to create a new patient in the specified Environment.\n \n\nCurrent supported timezones to be used in patient creation:\n\n \nUS/Eastern, \nUS/Central, \nUS/Mountain, \nUS/Pacific, \nUS/Alaska, \nUS/Arizona, \nUS/Hawaii, \nWET, \nCET, \nEET, \nAsia/Dubai, \nAsia/Singapore, \nAustralia/Perth, \nAustralia/Darwin, \nAustralia/Brisbane, \nAustralia/Adelaide, \nAustralia/Broken_Hill, \nAntarctica/Casey, \nAustralia/Hobart, \nAustralia/Sydney, \nAustralia/Lord_Howe"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"Size":{"name":"size","in":"query","required":false,"description":"Number of results per page","schema":{"type":"integer","default":20,"minimum":1,"maximum":1000}},"Sort":{"name":"sort","in":"query","required":false,"description":"Sort field and direction, e.g. `lastName,asc` or `createdAt,desc`","schema":{"type":"string"}}},"schemas":{"PatientPage":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/PatientResponse"}}}}]},"PaginatedResponse":{"type":"object","description":"Standard paginated response wrapper.","properties":{"content":{"type":"array","items":{"type":"object"}},"pageable":{"$ref":"#/components/schemas/PageableInfo"},"totalElements":{"type":"integer","description":"Total number of matching records"},"totalPages":{"type":"integer","description":"Total number of pages"},"last":{"type":"boolean"},"first":{"type":"boolean"},"number":{"type":"integer","description":"Current page number (zero-based)"},"size":{"type":"integer","description":"Page size"},"numberOfElements":{"type":"integer","description":"Number of elements on the current page"},"empty":{"type":"boolean"},"sort":{"$ref":"#/components/schemas/SortInfo"}}},"PageableInfo":{"type":"object","properties":{"sort":{"$ref":"#/components/schemas/SortInfo"},"pageSize":{"type":"integer"},"pageNumber":{"type":"integer"},"offset":{"type":"integer"},"unpaged":{"type":"boolean"},"paged":{"type":"boolean"}}},"SortInfo":{"type":"object","properties":{"sorted":{"type":"boolean"},"unsorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"PatientResponse":{"type":"object","description":"Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"externalGuid":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"mrn":{"type":"string","nullable":true},"nric":{"type":"string","nullable":true},"accessCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string","nullable":true},"birthDate":{"type":"string","format":"date-time","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"email":{"type":"string","format":"email","nullable":true},"secondaryEmail":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"phoneLabel":{"type":"string","nullable":true},"primaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"secondaryPhone":{"type":"string","nullable":true},"secondaryPhoneLabel":{"type":"string","nullable":true},"secondaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"preferableInstancePhoneId":{"type":"string","format":"uuid","nullable":true},"country":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string","nullable":true},"careTeamMembers":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"readOnly":true,"description":"Deprecated — use careTeam."},"patientPrograms":{"type":"array","items":{"$ref":"#/components/schemas/PatientProgram"},"readOnly":true},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"}},"territorialTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"},"readOnly":true,"description":"Only populated when the `expand=true` query param is set."},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string","nullable":true},"patientRegionTitle":{"type":"string","readOnly":true,"nullable":true},"patientTerritory":{"type":"string","nullable":true},"pointOfContact":{"$ref":"#/components/schemas/PatientTeamMember","nullable":true}}},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"MaritalStatus":{"type":"string","enum":["A","D","I","L","M","P","S","T","U","W","UKN"],"description":"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"},"PatientLanguage":{"type":"string","enum":["ENGLISH","SPANISH","FRENCH","PORTUGUESE","GERMAN","ITALIAN","ARABIC","CHINESE","MANDARIN","VIETNAMESE","JAPANESE","RUSSIAN","ALBANIAN","OTHER"]},"PhoneCapability":{"type":"string","enum":["VOICE_CALL","SMS","WHATS_APP"]},"PatientType":{"type":"string","enum":["ADULT","MINOR","COUPLE"]},"CareTeamMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"User UUID"},"pointOfContact":{"type":"boolean","description":"Whether this member is the point of contact"}},"required":["id"]},"PatientProgram":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdByName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedByName":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"programName":{"type":"string"},"programTitle":{"type":"string"},"programDescription":{"type":"string","nullable":true},"assigned":{"type":"boolean","default":true},"patientId":{"type":"string","format":"uuid"},"currentPhase":{"$ref":"#/components/schemas/PatientPhase"},"status":{"$ref":"#/components/schemas/PatientProgramStatus"},"compatibleWithCurrentVersion":{"type":"boolean"},"pathHistory":{"type":"array","items":{"$ref":"#/components/schemas/PatientPhase"}}}},"PatientPhase":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"currentVersion":{"type":"string"},"deleted":{"type":"boolean"}}},"PatientProgramStatus":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","INTERRUPTED","FINISHED"]},"PatientTeamMember":{"type":"object","description":"Full care team member representation returned on Patient reads.","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/SimpleRole"}},"pointOfContact":{"type":"boolean"},"enabled":{"type":"boolean"}}},"SimpleRole":{"type":"object","properties":{"name":{"type":"string"},"primaryRole":{"type":"boolean"},"description":{"type":"string","nullable":true},"instanceId":{"type":"string","format":"uuid","nullable":true}}},"PatientCadence":{"type":"object","required":["priority"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/CadenceSchedule"}},"priority":{"$ref":"#/components/schemas/PatientCadencePriority"}}},"CadenceSchedule":{"type":"object","properties":{"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayOfWeek"}},"weekNumbers":{"type":"array","items":{"type":"integer"}}}},"DayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"PatientCadencePriority":{"type":"string","enum":["LOW","MEDIUM","HIGH"]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients":{"get":{"summary":"Find a Patient","tags":["Patient"],"operationId":"Find_a_Patient","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/Size"},{"$ref":"#/components/parameters/Sort"},{"name":"search","in":"query","required":false,"description":"A list of fields available for searching using this parameter can be found on the Overview tab.","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"schema":{"type":"string"}},{"name":"mrn","in":"query","required":false,"schema":{"type":"string"}},{"name":"birthDate","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"withoutRegion","in":"query","required":false,"schema":{"type":"boolean"},"description":"true/false"},{"name":"withoutTerritory","in":"query","required":false,"schema":{"type":"boolean"},"description":"true/false"}],"responses":{"200":{"description":"Paginated list of patients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"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.\n\nThe **search** parameter can search for the following values:\n\n- string from FIRST_NAME + MIDLE_NAME + LAST_NAME\n \n- PHONE\n \n- SECONDARY_PHONE\n \n- EMAIL\n \n- SECONDARY_EMAIL\n \n- MRN\n \n- NRIC\n \n- ACCESS_CODE"}}}} ``` ## Create a Patient > Creating a new Patient in Welkin involves making a POST request to the Patient Collection resource.\ > \ > \*\*HTTP URL:\*\* \` > \ > \*\*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: \ > +61403211111 correct phone format \ > +61\*\*0\*\*403211111 incorrect phone format ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Patient","description":"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.\n\nThe endpoint for interacting with patients is as follows:\n\nURL Structure: `https://api.live.welkincloud.io/{tenant}/{environment}/patients`\n\nIn our demonstration context, the URL would be `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\nThe patient collection API provides several functionalities:\n\n1. **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.\n2. **Filter Patients:** This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.\n3. **Create a New Patient:** This operation allows users to create a new patient in the specified Environment.\n \n\nCurrent supported timezones to be used in patient creation:\n\n \nUS/Eastern, \nUS/Central, \nUS/Mountain, \nUS/Pacific, \nUS/Alaska, \nUS/Arizona, \nUS/Hawaii, \nWET, \nCET, \nEET, \nAsia/Dubai, \nAsia/Singapore, \nAustralia/Perth, \nAustralia/Darwin, \nAustralia/Brisbane, \nAustralia/Adelaide, \nAustralia/Broken_Hill, \nAntarctica/Casey, \nAustralia/Hobart, \nAustralia/Sydney, \nAustralia/Lord_Howe"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"PatientResponse":{"type":"object","description":"Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"externalGuid":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"mrn":{"type":"string","nullable":true},"nric":{"type":"string","nullable":true},"accessCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string","nullable":true},"birthDate":{"type":"string","format":"date-time","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"email":{"type":"string","format":"email","nullable":true},"secondaryEmail":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"phoneLabel":{"type":"string","nullable":true},"primaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"secondaryPhone":{"type":"string","nullable":true},"secondaryPhoneLabel":{"type":"string","nullable":true},"secondaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"preferableInstancePhoneId":{"type":"string","format":"uuid","nullable":true},"country":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string","nullable":true},"careTeamMembers":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"readOnly":true,"description":"Deprecated — use careTeam."},"patientPrograms":{"type":"array","items":{"$ref":"#/components/schemas/PatientProgram"},"readOnly":true},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"}},"territorialTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"},"readOnly":true,"description":"Only populated when the `expand=true` query param is set."},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string","nullable":true},"patientRegionTitle":{"type":"string","readOnly":true,"nullable":true},"patientTerritory":{"type":"string","nullable":true},"pointOfContact":{"$ref":"#/components/schemas/PatientTeamMember","nullable":true}}},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"MaritalStatus":{"type":"string","enum":["A","D","I","L","M","P","S","T","U","W","UKN"],"description":"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"},"PatientLanguage":{"type":"string","enum":["ENGLISH","SPANISH","FRENCH","PORTUGUESE","GERMAN","ITALIAN","ARABIC","CHINESE","MANDARIN","VIETNAMESE","JAPANESE","RUSSIAN","ALBANIAN","OTHER"]},"PhoneCapability":{"type":"string","enum":["VOICE_CALL","SMS","WHATS_APP"]},"PatientType":{"type":"string","enum":["ADULT","MINOR","COUPLE"]},"CareTeamMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"User UUID"},"pointOfContact":{"type":"boolean","description":"Whether this member is the point of contact"}},"required":["id"]},"PatientProgram":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdByName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedByName":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"programName":{"type":"string"},"programTitle":{"type":"string"},"programDescription":{"type":"string","nullable":true},"assigned":{"type":"boolean","default":true},"patientId":{"type":"string","format":"uuid"},"currentPhase":{"$ref":"#/components/schemas/PatientPhase"},"status":{"$ref":"#/components/schemas/PatientProgramStatus"},"compatibleWithCurrentVersion":{"type":"boolean"},"pathHistory":{"type":"array","items":{"$ref":"#/components/schemas/PatientPhase"}}}},"PatientPhase":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"currentVersion":{"type":"string"},"deleted":{"type":"boolean"}}},"PatientProgramStatus":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","INTERRUPTED","FINISHED"]},"PatientTeamMember":{"type":"object","description":"Full care team member representation returned on Patient reads.","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/SimpleRole"}},"pointOfContact":{"type":"boolean"},"enabled":{"type":"boolean"}}},"SimpleRole":{"type":"object","properties":{"name":{"type":"string"},"primaryRole":{"type":"boolean"},"description":{"type":"string","nullable":true},"instanceId":{"type":"string","format":"uuid","nullable":true}}},"PatientCadence":{"type":"object","required":["priority"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/CadenceSchedule"}},"priority":{"$ref":"#/components/schemas/PatientCadencePriority"}}},"CadenceSchedule":{"type":"object","properties":{"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayOfWeek"}},"weekNumbers":{"type":"array","items":{"type":"integer"}}}},"DayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"PatientCadencePriority":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"PatientRequest":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format, e.g. `+14155552671`"},"birthDate":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"externalGuid":{"type":"string","format":"uuid"},"country":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"patientTerritories":{"type":"array","items":{"$ref":"#/components/schemas/PatientTerritory"}},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"description":"Care team members. One must have pointOfContact: true."},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryEmail":{"type":"string","format":"email"},"phoneLabel":{"type":"string"},"secondaryPhone":{"type":"string","description":"E.164 format"},"secondaryPhoneLabel":{"type":"string"},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string"},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string"},"patientTerritory":{"type":"string"}}},"PatientTerritory":{"type":"object","properties":{"name":{"type":"string","description":"Territory group name"},"territories":{"type":"array","items":{"type":"string"},"description":"List of territory names within the group"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients":{"post":{"summary":"Create a Patient","tags":["Patient"],"operationId":"Create_a_Patient","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"responses":{"201":{"description":"Patient created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Creating a new Patient in Welkin involves making a POST request to the Patient Collection resource.\n\n**HTTP URL:** `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\n**HTTP Response Codes:**\n\n- 201: Successfully created a new patient\n \n- 400: Bad request - the request could not be understood or was missing required parameters\n \n- 500: Internal server error - something went wrong on the server\n \n\n**Notes:**\n\n_\"firstName\" and \"lastName\" are required fields. Another fields depends on Designer settings._\n\n1. **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.\n \n2. **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.\n \n3. **phone:** when working with patients and fields such as phone, phone must be specified in the international format, E.164 format, without zero \n example for Australia: \n +61403211111 correct phone format \n +61**0**403211111 incorrect phone format","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientRequest"}}}}}}}} ``` ## Bulk update for Patients > \> 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) ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Patient","description":"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.\n\nThe endpoint for interacting with patients is as follows:\n\nURL Structure: `https://api.live.welkincloud.io/{tenant}/{environment}/patients`\n\nIn our demonstration context, the URL would be `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\nThe patient collection API provides several functionalities:\n\n1. **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.\n2. **Filter Patients:** This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.\n3. **Create a New Patient:** This operation allows users to create a new patient in the specified Environment.\n \n\nCurrent supported timezones to be used in patient creation:\n\n \nUS/Eastern, \nUS/Central, \nUS/Mountain, \nUS/Pacific, \nUS/Alaska, \nUS/Arizona, \nUS/Hawaii, \nWET, \nCET, \nEET, \nAsia/Dubai, \nAsia/Singapore, \nAustralia/Perth, \nAustralia/Darwin, \nAustralia/Brisbane, \nAustralia/Adelaide, \nAustralia/Broken_Hill, \nAntarctica/Casey, \nAustralia/Hobart, \nAustralia/Sydney, \nAustralia/Lord_Howe"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"PatientResponse":{"type":"object","description":"Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"externalGuid":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"mrn":{"type":"string","nullable":true},"nric":{"type":"string","nullable":true},"accessCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string","nullable":true},"birthDate":{"type":"string","format":"date-time","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"email":{"type":"string","format":"email","nullable":true},"secondaryEmail":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"phoneLabel":{"type":"string","nullable":true},"primaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"secondaryPhone":{"type":"string","nullable":true},"secondaryPhoneLabel":{"type":"string","nullable":true},"secondaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"preferableInstancePhoneId":{"type":"string","format":"uuid","nullable":true},"country":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string","nullable":true},"careTeamMembers":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"readOnly":true,"description":"Deprecated — use careTeam."},"patientPrograms":{"type":"array","items":{"$ref":"#/components/schemas/PatientProgram"},"readOnly":true},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"}},"territorialTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"},"readOnly":true,"description":"Only populated when the `expand=true` query param is set."},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string","nullable":true},"patientRegionTitle":{"type":"string","readOnly":true,"nullable":true},"patientTerritory":{"type":"string","nullable":true},"pointOfContact":{"$ref":"#/components/schemas/PatientTeamMember","nullable":true}}},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"MaritalStatus":{"type":"string","enum":["A","D","I","L","M","P","S","T","U","W","UKN"],"description":"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"},"PatientLanguage":{"type":"string","enum":["ENGLISH","SPANISH","FRENCH","PORTUGUESE","GERMAN","ITALIAN","ARABIC","CHINESE","MANDARIN","VIETNAMESE","JAPANESE","RUSSIAN","ALBANIAN","OTHER"]},"PhoneCapability":{"type":"string","enum":["VOICE_CALL","SMS","WHATS_APP"]},"PatientType":{"type":"string","enum":["ADULT","MINOR","COUPLE"]},"CareTeamMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"User UUID"},"pointOfContact":{"type":"boolean","description":"Whether this member is the point of contact"}},"required":["id"]},"PatientProgram":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdByName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedByName":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"programName":{"type":"string"},"programTitle":{"type":"string"},"programDescription":{"type":"string","nullable":true},"assigned":{"type":"boolean","default":true},"patientId":{"type":"string","format":"uuid"},"currentPhase":{"$ref":"#/components/schemas/PatientPhase"},"status":{"$ref":"#/components/schemas/PatientProgramStatus"},"compatibleWithCurrentVersion":{"type":"boolean"},"pathHistory":{"type":"array","items":{"$ref":"#/components/schemas/PatientPhase"}}}},"PatientPhase":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"currentVersion":{"type":"string"},"deleted":{"type":"boolean"}}},"PatientProgramStatus":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","INTERRUPTED","FINISHED"]},"PatientTeamMember":{"type":"object","description":"Full care team member representation returned on Patient reads.","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/SimpleRole"}},"pointOfContact":{"type":"boolean"},"enabled":{"type":"boolean"}}},"SimpleRole":{"type":"object","properties":{"name":{"type":"string"},"primaryRole":{"type":"boolean"},"description":{"type":"string","nullable":true},"instanceId":{"type":"string","format":"uuid","nullable":true}}},"PatientCadence":{"type":"object","required":["priority"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/CadenceSchedule"}},"priority":{"$ref":"#/components/schemas/PatientCadencePriority"}}},"CadenceSchedule":{"type":"object","properties":{"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayOfWeek"}},"weekNumbers":{"type":"array","items":{"type":"integer"}}}},"DayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"PatientCadencePriority":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"PatientBulkUpdateRequest":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1},"timezone":{"type":"string"},"patientTerritories":{"type":"array","items":{"$ref":"#/components/schemas/PatientTerritory"}},"patientRegion":{"type":"string"},"patientTerritory":{"type":"string"},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"}},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"careTeamAdditions":{"type":"array","items":{"type":"string","format":"uuid"}},"careTeamReplacements":{"type":"array","items":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"uuid"},"to":{"type":"string","format":"uuid"}}}},"careTeamRemovals":{"type":"array","items":{"type":"string","format":"uuid"}}}},"PatientTerritory":{"type":"object","properties":{"name":{"type":"string","description":"Territory group name"},"territories":{"type":"array","items":{"type":"string"},"description":"List of territory names within the group"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients":{"patch":{"summary":"Bulk update for Patients","tags":["Patient"],"operationId":"Bulk_update_for_Patients","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"responses":{"200":{"description":"Updated patients","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PatientResponse"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"> 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. \n \n\nThe query allows you to update patient information in bulk\n\n_ids_ - list of patient IDs for which to apply changes\n\n_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)\n\n_careTeamReplacements_ - the block allows you to replace one user in the patient care team with a different one\n\n_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)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientBulkUpdateRequest"}}}}}}}} ``` ## Get a specific Patient By ID, externalID, externalGUID, MRN > 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:\*\* \` > \ > \*\*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\. \[ > 2\. \[ > 3\. \[ > 4\. \[ ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Patient","description":"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.\n\nThe endpoint for interacting with patients is as follows:\n\nURL Structure: `https://api.live.welkincloud.io/{tenant}/{environment}/patients`\n\nIn our demonstration context, the URL would be `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\nThe patient collection API provides several functionalities:\n\n1. **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.\n2. **Filter Patients:** This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.\n3. **Create a New Patient:** This operation allows users to create a new patient in the specified Environment.\n \n\nCurrent supported timezones to be used in patient creation:\n\n \nUS/Eastern, \nUS/Central, \nUS/Mountain, \nUS/Pacific, \nUS/Alaska, \nUS/Arizona, \nUS/Hawaii, \nWET, \nCET, \nEET, \nAsia/Dubai, \nAsia/Singapore, \nAustralia/Perth, \nAustralia/Darwin, \nAustralia/Brisbane, \nAustralia/Adelaide, \nAustralia/Broken_Hill, \nAntarctica/Casey, \nAustralia/Hobart, \nAustralia/Sydney, \nAustralia/Lord_Howe"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"PatientId":{"name":"patientId","in":"path","required":true,"description":"UUID of the patient record","schema":{"type":"string","format":"uuid"}}},"schemas":{"PatientResponse":{"type":"object","description":"Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"externalGuid":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"mrn":{"type":"string","nullable":true},"nric":{"type":"string","nullable":true},"accessCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string","nullable":true},"birthDate":{"type":"string","format":"date-time","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"email":{"type":"string","format":"email","nullable":true},"secondaryEmail":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"phoneLabel":{"type":"string","nullable":true},"primaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"secondaryPhone":{"type":"string","nullable":true},"secondaryPhoneLabel":{"type":"string","nullable":true},"secondaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"preferableInstancePhoneId":{"type":"string","format":"uuid","nullable":true},"country":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string","nullable":true},"careTeamMembers":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"readOnly":true,"description":"Deprecated — use careTeam."},"patientPrograms":{"type":"array","items":{"$ref":"#/components/schemas/PatientProgram"},"readOnly":true},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"}},"territorialTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"},"readOnly":true,"description":"Only populated when the `expand=true` query param is set."},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string","nullable":true},"patientRegionTitle":{"type":"string","readOnly":true,"nullable":true},"patientTerritory":{"type":"string","nullable":true},"pointOfContact":{"$ref":"#/components/schemas/PatientTeamMember","nullable":true}}},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"MaritalStatus":{"type":"string","enum":["A","D","I","L","M","P","S","T","U","W","UKN"],"description":"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"},"PatientLanguage":{"type":"string","enum":["ENGLISH","SPANISH","FRENCH","PORTUGUESE","GERMAN","ITALIAN","ARABIC","CHINESE","MANDARIN","VIETNAMESE","JAPANESE","RUSSIAN","ALBANIAN","OTHER"]},"PhoneCapability":{"type":"string","enum":["VOICE_CALL","SMS","WHATS_APP"]},"PatientType":{"type":"string","enum":["ADULT","MINOR","COUPLE"]},"CareTeamMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"User UUID"},"pointOfContact":{"type":"boolean","description":"Whether this member is the point of contact"}},"required":["id"]},"PatientProgram":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdByName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedByName":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"programName":{"type":"string"},"programTitle":{"type":"string"},"programDescription":{"type":"string","nullable":true},"assigned":{"type":"boolean","default":true},"patientId":{"type":"string","format":"uuid"},"currentPhase":{"$ref":"#/components/schemas/PatientPhase"},"status":{"$ref":"#/components/schemas/PatientProgramStatus"},"compatibleWithCurrentVersion":{"type":"boolean"},"pathHistory":{"type":"array","items":{"$ref":"#/components/schemas/PatientPhase"}}}},"PatientPhase":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"currentVersion":{"type":"string"},"deleted":{"type":"boolean"}}},"PatientProgramStatus":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","INTERRUPTED","FINISHED"]},"PatientTeamMember":{"type":"object","description":"Full care team member representation returned on Patient reads.","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/SimpleRole"}},"pointOfContact":{"type":"boolean"},"enabled":{"type":"boolean"}}},"SimpleRole":{"type":"object","properties":{"name":{"type":"string"},"primaryRole":{"type":"boolean"},"description":{"type":"string","nullable":true},"instanceId":{"type":"string","format":"uuid","nullable":true}}},"PatientCadence":{"type":"object","required":["priority"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/CadenceSchedule"}},"priority":{"$ref":"#/components/schemas/PatientCadencePriority"}}},"CadenceSchedule":{"type":"object","properties":{"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayOfWeek"}},"weekNumbers":{"type":"array","items":{"type":"integer"}}}},"DayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"PatientCadencePriority":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"PatientRequest":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format, e.g. `+14155552671`"},"birthDate":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"externalGuid":{"type":"string","format":"uuid"},"country":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"patientTerritories":{"type":"array","items":{"$ref":"#/components/schemas/PatientTerritory"}},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"description":"Care team members. One must have pointOfContact: true."},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryEmail":{"type":"string","format":"email"},"phoneLabel":{"type":"string"},"secondaryPhone":{"type":"string","description":"E.164 format"},"secondaryPhoneLabel":{"type":"string"},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string"},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string"},"patientTerritory":{"type":"string"}}},"PatientTerritory":{"type":"object","properties":{"name":{"type":"string","description":"Territory group name"},"territories":{"type":"array","items":{"type":"string"},"description":"List of territory names within the group"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients/{patientId}":{"get":{"summary":"Get a specific Patient By ID, externalID, externalGUID, MRN","tags":["Patient"],"operationId":"Get_a_specific_Patient_By_ID_externalID_externalGUID_MRN","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/PatientId"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"Type of identifier: ID, EID, EGUID, MRN (default ID)"},{"name":"expand","in":"query","required":false,"schema":{"type":"string"},"description":"If true, request will return dto with territorialTeam field (default false)"}],"responses":{"200":{"description":"Patient record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"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).\n\n**HTTP URL:** `https://api.live.welkincloud.io/gh/sb-demo/patients/{identifier}?type={type}`\n\n**HTTP Response Codes:**\n\n- 200: Successfully retrieved the patient's details\n- 400: Bad request - the request could not be understood or was missing required parameters\n- 500: Internal server error - something went wrong on the server\n \n\nHere are a few examples illustrating how you can use different identifiers to retrieve a patient:\n\n1. [https://api.live.welkincloud.io/gh/sb-demo/patients/someId?type=EID](https://api.live.welkincloud.io/gh/sb-demo/patients/someId?type=EID)\n2. [https://api.live.welkincloud.io/gh/sb-demo/patients/123e4567-e89b-12d3-a456-426655440000?type=EGUID](https://api.live.welkincloud.io/gh/sb-demo/patients/123e4567-e89b-12d3-a456-426655440000?type=EGUID)\n3. [https://api.live.welkincloud.io/gh/sb-demo/patients/someMRN?type=MRN](https://api.live.welkincloud.io/gh/sb-demo/patients/someMRN?type=MRN)\n4. [https://api.live.welkincloud.io/gh/sb-demo/patients/someId?type=EID&expand=true](https://api.live.welkincloud.io/gh/sb-demo/patients/someId?type=EID&expand=true)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientRequest"}}}}}}}} ``` ## Delete Patient by ID > \*\*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. ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Patient","description":"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.\n\nThe endpoint for interacting with patients is as follows:\n\nURL Structure: `https://api.live.welkincloud.io/{tenant}/{environment}/patients`\n\nIn our demonstration context, the URL would be `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\nThe patient collection API provides several functionalities:\n\n1. **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.\n2. **Filter Patients:** This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.\n3. **Create a New Patient:** This operation allows users to create a new patient in the specified Environment.\n \n\nCurrent supported timezones to be used in patient creation:\n\n \nUS/Eastern, \nUS/Central, \nUS/Mountain, \nUS/Pacific, \nUS/Alaska, \nUS/Arizona, \nUS/Hawaii, \nWET, \nCET, \nEET, \nAsia/Dubai, \nAsia/Singapore, \nAustralia/Perth, \nAustralia/Darwin, \nAustralia/Brisbane, \nAustralia/Adelaide, \nAustralia/Broken_Hill, \nAntarctica/Casey, \nAustralia/Hobart, \nAustralia/Sydney, \nAustralia/Lord_Howe"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"PatientId":{"name":"patientId","in":"path","required":true,"description":"UUID of the patient record","schema":{"type":"string","format":"uuid"}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients/{patientId}":{"delete":{"summary":"Delete Patient by ID","tags":["Patient"],"operationId":"Delete_Patient_by_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/PatientId"},{"name":"type","in":"query","required":false,"schema":{"type":"string"},"description":"ID,EGUID"}],"responses":{"200":{"description":"Patient deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"**Description:** \nThis 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.\n\n**Parameters:**\n\n- `url`: The base URL of the API.\n- `tenantName`: The name or identifier of the tenant within which the patient record exists.\n- `instanceName`: The name or identifier of the specific instance under the given tenant.\n- `patientId`: The unique identifier of the patient record you want to delete.\n \n\n**Request Headers:** \nNo special headers are required for this request.\n\n**Request Body:** \nThis endpoint does not require a request body.\n\n**Response:**\n\n- **204 No Content**: The request was successful, and the patient record has been deleted. No response body will be returned.\n- **404 Not Found**: The requested patient or resource was not found. An error message or response body may provide additional information.\n \n\n**Authorization:** \nEnsure that the caller of this endpoint has the necessary permissions to delete patient records. Implement appropriate authentication and authorization mechanisms.\n\n**Usage:** \nBefore 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.\n\n**Notes:**\n\n- Deleting a patient record is irreversible, so exercise caution while using this endpoint."}}}} ``` ## Update a specific Patient By ID > To update a patient by a known ID\ > \ > 1\. HTTP Method: PATCH\ > 2\. HTTP URL: \` > 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 ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Patient","description":"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.\n\nThe endpoint for interacting with patients is as follows:\n\nURL Structure: `https://api.live.welkincloud.io/{tenant}/{environment}/patients`\n\nIn our demonstration context, the URL would be `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\nThe patient collection API provides several functionalities:\n\n1. **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.\n2. **Filter Patients:** This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.\n3. **Create a New Patient:** This operation allows users to create a new patient in the specified Environment.\n \n\nCurrent supported timezones to be used in patient creation:\n\n \nUS/Eastern, \nUS/Central, \nUS/Mountain, \nUS/Pacific, \nUS/Alaska, \nUS/Arizona, \nUS/Hawaii, \nWET, \nCET, \nEET, \nAsia/Dubai, \nAsia/Singapore, \nAustralia/Perth, \nAustralia/Darwin, \nAustralia/Brisbane, \nAustralia/Adelaide, \nAustralia/Broken_Hill, \nAntarctica/Casey, \nAustralia/Hobart, \nAustralia/Sydney, \nAustralia/Lord_Howe"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"PatientId":{"name":"patientId","in":"path","required":true,"description":"UUID of the patient record","schema":{"type":"string","format":"uuid"}}},"schemas":{"PatientResponse":{"type":"object","description":"Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"externalGuid":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"mrn":{"type":"string","nullable":true},"nric":{"type":"string","nullable":true},"accessCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string","nullable":true},"birthDate":{"type":"string","format":"date-time","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"email":{"type":"string","format":"email","nullable":true},"secondaryEmail":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"phoneLabel":{"type":"string","nullable":true},"primaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"secondaryPhone":{"type":"string","nullable":true},"secondaryPhoneLabel":{"type":"string","nullable":true},"secondaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"preferableInstancePhoneId":{"type":"string","format":"uuid","nullable":true},"country":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string","nullable":true},"careTeamMembers":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"readOnly":true,"description":"Deprecated — use careTeam."},"patientPrograms":{"type":"array","items":{"$ref":"#/components/schemas/PatientProgram"},"readOnly":true},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"}},"territorialTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"},"readOnly":true,"description":"Only populated when the `expand=true` query param is set."},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string","nullable":true},"patientRegionTitle":{"type":"string","readOnly":true,"nullable":true},"patientTerritory":{"type":"string","nullable":true},"pointOfContact":{"$ref":"#/components/schemas/PatientTeamMember","nullable":true}}},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"MaritalStatus":{"type":"string","enum":["A","D","I","L","M","P","S","T","U","W","UKN"],"description":"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"},"PatientLanguage":{"type":"string","enum":["ENGLISH","SPANISH","FRENCH","PORTUGUESE","GERMAN","ITALIAN","ARABIC","CHINESE","MANDARIN","VIETNAMESE","JAPANESE","RUSSIAN","ALBANIAN","OTHER"]},"PhoneCapability":{"type":"string","enum":["VOICE_CALL","SMS","WHATS_APP"]},"PatientType":{"type":"string","enum":["ADULT","MINOR","COUPLE"]},"CareTeamMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"User UUID"},"pointOfContact":{"type":"boolean","description":"Whether this member is the point of contact"}},"required":["id"]},"PatientProgram":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdByName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedByName":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"programName":{"type":"string"},"programTitle":{"type":"string"},"programDescription":{"type":"string","nullable":true},"assigned":{"type":"boolean","default":true},"patientId":{"type":"string","format":"uuid"},"currentPhase":{"$ref":"#/components/schemas/PatientPhase"},"status":{"$ref":"#/components/schemas/PatientProgramStatus"},"compatibleWithCurrentVersion":{"type":"boolean"},"pathHistory":{"type":"array","items":{"$ref":"#/components/schemas/PatientPhase"}}}},"PatientPhase":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"currentVersion":{"type":"string"},"deleted":{"type":"boolean"}}},"PatientProgramStatus":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","INTERRUPTED","FINISHED"]},"PatientTeamMember":{"type":"object","description":"Full care team member representation returned on Patient reads.","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/SimpleRole"}},"pointOfContact":{"type":"boolean"},"enabled":{"type":"boolean"}}},"SimpleRole":{"type":"object","properties":{"name":{"type":"string"},"primaryRole":{"type":"boolean"},"description":{"type":"string","nullable":true},"instanceId":{"type":"string","format":"uuid","nullable":true}}},"PatientCadence":{"type":"object","required":["priority"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/CadenceSchedule"}},"priority":{"$ref":"#/components/schemas/PatientCadencePriority"}}},"CadenceSchedule":{"type":"object","properties":{"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayOfWeek"}},"weekNumbers":{"type":"array","items":{"type":"integer"}}}},"DayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"PatientCadencePriority":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"PatientUpdateRequest":{"type":"object","description":"Partial update — all fields optional. Omitted fields are left unchanged.","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"E.164 format, e.g. `+14155552671`"},"birthDate":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"externalGuid":{"type":"string","format":"uuid"},"country":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"patientTerritories":{"type":"array","items":{"$ref":"#/components/schemas/PatientTerritory"}},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"description":"Care team members. One must have pointOfContact: true."},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryEmail":{"type":"string","format":"email"},"phoneLabel":{"type":"string"},"secondaryPhone":{"type":"string","description":"E.164 format"},"secondaryPhoneLabel":{"type":"string"},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string"},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string"},"patientTerritory":{"type":"string"}}},"PatientTerritory":{"type":"object","properties":{"name":{"type":"string","description":"Territory group name"},"territories":{"type":"array","items":{"type":"string"},"description":"List of territory names within the group"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients/{patientId}":{"patch":{"summary":"Update a specific Patient By ID","tags":["Patient"],"operationId":"Update_a_specific_Patient_By_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/PatientId"}],"responses":{"200":{"description":"Updated patient","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"To update a patient by a known ID\n\n1. HTTP Method: PATCH\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/patients/6801d498-26f4-4aee-961b-5daffcf193c8`\n3. HTTP Response Codes: 200, 400, 404, 500\n \n\n**Note:**\n\n- **phone:** when working with patients and fields such as phone, phone must be specified in the international format, E.164 format, without zero\n- **careTeamMembers** is deprecated, use only **careTeam** to update","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientUpdateRequest"}}}}}}}} ``` ## Find by filters > 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": "" ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Patient","description":"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.\n\nThe endpoint for interacting with patients is as follows:\n\nURL Structure: `https://api.live.welkincloud.io/{tenant}/{environment}/patients`\n\nIn our demonstration context, the URL would be `https://api.live.welkincloud.io/gh/sb-demo/patients`\n\nThe patient collection API provides several functionalities:\n\n1. **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.\n2. **Filter Patients:** This operation, often referred to as 'FINDER', allows users to retrieve a list of patients filtered by a specified email address.\n3. **Create a New Patient:** This operation allows users to create a new patient in the specified Environment.\n \n\nCurrent supported timezones to be used in patient creation:\n\n \nUS/Eastern, \nUS/Central, \nUS/Mountain, \nUS/Pacific, \nUS/Alaska, \nUS/Arizona, \nUS/Hawaii, \nWET, \nCET, \nEET, \nAsia/Dubai, \nAsia/Singapore, \nAustralia/Perth, \nAustralia/Darwin, \nAustralia/Brisbane, \nAustralia/Adelaide, \nAustralia/Broken_Hill, \nAntarctica/Casey, \nAustralia/Hobart, \nAustralia/Sydney, \nAustralia/Lord_Howe"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"PatientPage":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/PatientResponse"}}}}]},"PaginatedResponse":{"type":"object","description":"Standard paginated response wrapper.","properties":{"content":{"type":"array","items":{"type":"object"}},"pageable":{"$ref":"#/components/schemas/PageableInfo"},"totalElements":{"type":"integer","description":"Total number of matching records"},"totalPages":{"type":"integer","description":"Total number of pages"},"last":{"type":"boolean"},"first":{"type":"boolean"},"number":{"type":"integer","description":"Current page number (zero-based)"},"size":{"type":"integer","description":"Page size"},"numberOfElements":{"type":"integer","description":"Number of elements on the current page"},"empty":{"type":"boolean"},"sort":{"$ref":"#/components/schemas/SortInfo"}}},"PageableInfo":{"type":"object","properties":{"sort":{"$ref":"#/components/schemas/SortInfo"},"pageSize":{"type":"integer"},"pageNumber":{"type":"integer"},"offset":{"type":"integer"},"unpaged":{"type":"boolean"},"paged":{"type":"boolean"}}},"SortInfo":{"type":"object","properties":{"sorted":{"type":"boolean"},"unsorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"PatientResponse":{"type":"object","description":"Patient record. Response is extensible — tenant-configured custom attributes appear as additional top-level properties beyond those listed here.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"externalGuid":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"mrn":{"type":"string","nullable":true},"nric":{"type":"string","nullable":true},"accessCode":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string","nullable":true},"birthDate":{"type":"string","format":"date-time","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"maritalStatus":{"$ref":"#/components/schemas/MaritalStatus"},"primaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"secondaryLanguage":{"$ref":"#/components/schemas/PatientLanguage"},"email":{"type":"string","format":"email","nullable":true},"secondaryEmail":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"phoneLabel":{"type":"string","nullable":true},"primaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"secondaryPhone":{"type":"string","nullable":true},"secondaryPhoneLabel":{"type":"string","nullable":true},"secondaryPhoneCapabilities":{"type":"array","items":{"$ref":"#/components/schemas/PhoneCapability"}},"preferableInstancePhoneId":{"type":"string","format":"uuid","nullable":true},"country":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"patientType":{"$ref":"#/components/schemas/PatientType"},"notes":{"type":"string","nullable":true},"careTeamMembers":{"type":"array","items":{"$ref":"#/components/schemas/CareTeamMember"},"readOnly":true,"description":"Deprecated — use careTeam."},"patientPrograms":{"type":"array","items":{"$ref":"#/components/schemas/PatientProgram"},"readOnly":true},"careTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"}},"territorialTeam":{"type":"array","items":{"$ref":"#/components/schemas/PatientTeamMember"},"readOnly":true,"description":"Only populated when the `expand=true` query param is set."},"cadence":{"type":"array","items":{"$ref":"#/components/schemas/PatientCadence"}},"patientRegion":{"type":"string","nullable":true},"patientRegionTitle":{"type":"string","readOnly":true,"nullable":true},"patientTerritory":{"type":"string","nullable":true},"pointOfContact":{"$ref":"#/components/schemas/PatientTeamMember","nullable":true}}},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"MaritalStatus":{"type":"string","enum":["A","D","I","L","M","P","S","T","U","W","UKN"],"description":"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"},"PatientLanguage":{"type":"string","enum":["ENGLISH","SPANISH","FRENCH","PORTUGUESE","GERMAN","ITALIAN","ARABIC","CHINESE","MANDARIN","VIETNAMESE","JAPANESE","RUSSIAN","ALBANIAN","OTHER"]},"PhoneCapability":{"type":"string","enum":["VOICE_CALL","SMS","WHATS_APP"]},"PatientType":{"type":"string","enum":["ADULT","MINOR","COUPLE"]},"CareTeamMember":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"User UUID"},"pointOfContact":{"type":"boolean","description":"Whether this member is the point of contact"}},"required":["id"]},"PatientProgram":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdByName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedByName":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"programName":{"type":"string"},"programTitle":{"type":"string"},"programDescription":{"type":"string","nullable":true},"assigned":{"type":"boolean","default":true},"patientId":{"type":"string","format":"uuid"},"currentPhase":{"$ref":"#/components/schemas/PatientPhase"},"status":{"$ref":"#/components/schemas/PatientProgramStatus"},"compatibleWithCurrentVersion":{"type":"boolean"},"pathHistory":{"type":"array","items":{"$ref":"#/components/schemas/PatientPhase"}}}},"PatientPhase":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"currentVersion":{"type":"string"},"deleted":{"type":"boolean"}}},"PatientProgramStatus":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","INTERRUPTED","FINISHED"]},"PatientTeamMember":{"type":"object","description":"Full care team member representation returned on Patient reads.","properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/SimpleRole"}},"pointOfContact":{"type":"boolean"},"enabled":{"type":"boolean"}}},"SimpleRole":{"type":"object","properties":{"name":{"type":"string"},"primaryRole":{"type":"boolean"},"description":{"type":"string","nullable":true},"instanceId":{"type":"string","format":"uuid","nullable":true}}},"PatientCadence":{"type":"object","required":["priority"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/CadenceSchedule"}},"priority":{"$ref":"#/components/schemas/PatientCadencePriority"}}},"CadenceSchedule":{"type":"object","properties":{"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayOfWeek"}},"weekNumbers":{"type":"array","items":{"type":"integer"}}}},"DayOfWeek":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"PatientCadencePriority":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"PatientFilterRequest":{"type":"object","description":"Filter criteria for finding patients.","properties":{"search":{"type":"string","maxLength":50},"email":{"type":"string","format":"email"},"mrn":{"type":"string"},"birthDate":{"type":"string","format":"date-time"},"withoutRegion":{"type":"boolean"},"withoutTerritory":{"type":"boolean"},"timezones":{"type":"array","items":{"type":"string"}},"territories":{"type":"string"},"careTeamIds":{"type":"array","items":{"type":"string","format":"uuid"}},"cadence":{"type":"string"},"careTeamOnly":{"type":"boolean","default":false},"primaryContact":{"type":"boolean","default":false},"ids":{"type":"array","items":{"type":"string","format":"uuid"}},"dateStart":{"type":"string","format":"date-time"},"dateEnd":{"type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/by-filter/patients":{"post":{"summary":"Find by filters","tags":["Patient"],"operationId":"Find_by_filters","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"responses":{"200":{"description":"Paginated list of matching patients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientPage"}}}},"201":{"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Request to search for patients based on filters. It can accept different parameters:\n\n- timezones\n \n- withoutTimezone\n \n- cadence\n \n- territories\n \n- userRegions\n \n- regions\n \n- withoutRegion\n \n- withoutTerritory\n \n- careTeamOnly\n \n- primaryContact\n \n- careTeamIds\n \n- currentUserId\n \n- birthDate\n \n- programs\n \n- withoutProgram\n \n- phone\n \n- mrn\n \n- nric\n \n- accessCode\n \n\nYou 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:\n\n\"query\": \"testEmail@test.com\"","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientFilterRequest"}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.welkinhealth.com/api-reference/patient.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.