Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Contact

Communication with patient representatives. This feature is designed to empower customers in facilitating communication between their users and third-party entities associated with patients, such as legal guardians, providers, and relatives. It utilizes the comm center as a means of communication. According to Welkin’s design, these entities should be stored within profiles. To make a profile record contactable, two requirements must be met: 1) it should be linked / added as a contact to a patient, and 2) it should belong to a profile with the “contactable” switch enabled in the Designer, which is introduced as part of the current feature. Once these conditions are fulfilled, communication icons will appear next to phone numbers and emails on the profile record within a patient’s screen. Care users have the freedom to click on these icons to initiate communication with the relevant entities. Clicking on an icon will redirect the user to the comm center, where all standard features, including making and receiving calls, sending SMS, and emails, are available.

Before you begin using the Contacts API, please ensure that your API client is configured with the necessary policies to interact with patient data. Specifically, the "General - My Patients - Read and Update Policy" should be properly set.

Get All Contacts

get

Description

This endpoint retrieves the contacts associated with a specific patient. By making a GET request to this endpoint, you can retrieve a list of contacts related to the provided patient ID. Contacts may include information such as emergency contacts, primary care providers, or any other relevant individuals associated with the patient.

Parameters

The endpoint requires the following parameters:

  • {{url}}: The base URL of the API.

  • {{tenantName}}: The name of the tenant or organization.

  • {{instanceName}}: The name of the specific instance within the tenant.

  • {{patientId}}: The unique identifier of the patient for whom you want to retrieve the contacts.

Request Headers

The following headers must be included in the request:

  • Authorization: A token or credentials to authenticate the request.

  • Content-Type: The format of the request payload, typically set to application/json.

Response

The response to a successful request will include a list of contacts associated with the provided patient ID. Each contact may contain various fields, such as name, phone number, email, relationship, and additional details.

Error Handling

If an error occurs, the response will include an appropriate HTTP status code along with an error message or code to indicate the specific issue encountered. Common error codes include 400 for bad requests, 401 for unauthorized access, and 404 for not found.

Authorization

Proper authorization credentials must be provided in the request headers to access this endpoint. Consult the API documentation or contact the system administrator to obtain the necessary authorization details.

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
pdtRecordIdstringOptionalExample: a76221fe-74ef-4915-8d24-31832144a457
activestringOptionalExample: false
Responses
200

Paginated list of contacts

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
get/{tenantName}/{instanceName}/patients/{patientId}/contacts
GET /{tenantName}/{instanceName}/patients/{patientId}/contacts HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
      "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "updatedByName": "text",
      "name": "text",
      "email": "name@gmail.com",
      "emailLabel": "text",
      "emailPdtFieldName": "text",
      "phone": "text",
      "phoneLabel": "text",
      "phonePdtFieldName": "text",
      "secondaryPhone": "text",
      "secondaryPhoneLabel": "text",
      "secondaryPhonePdtFieldName": "text",
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "pdtRecordId": "123e4567-e89b-12d3-a456-426614174000",
      "relation": "text",
      "active": true
    }
  ],
  "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 Contact

post

Description

This endpoint allows you to create a new contact for a specific patient. The contact will be added to the patient's commcenter and can be communicated with. By making a POST request to this endpoint, you can add a contact record from the profile with relevant information such as name, phone number, email, and relationship to the patient.

Parameters

The endpoint requires the following parameters:

  • {{url}}: The base URL of the API.

  • {{tenantName}}: The name of the tenant or organization.

  • {{instanceName}}: The name of the specific instance within the tenant.

  • {{patientId}}: The unique identifier of the patient for whom the contact is being created.

Request Headers

The following headers must be included in the request:

  • Authorization: A token or credentials to authenticate the request.

  • Content-Type: The format of the request payload, typically set to application/json.

Request Body

The request body should contain the necessary information to create the contact. The required fields may include:

  • name: The name of the contact.

  • phone: The phone number of the contact. (Note: when working with patients and fields such as phone, phone must be specified in the international format, E.164 format, without zero)

  • email: The email address of the contact.

  • relationship: The relationship of the contact to the patient.

  • pdtRecordId : profile record ID

Response

The response to a successful request will include the newly created contact object, typically with an associated unique identifier.

Error Handling

If an error occurs, the response will include an appropriate HTTP status code along with an error message or code to indicate the specific issue encountered. Common error codes include 400 for bad requests and 401 for unauthorized access.

Authorization

Proper authorization credentials must be provided in the request headers to access this endpoint. Consult the API documentation or contact the system administrator to obtain the necessary authorization details.

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
namestringRequired
emailstring · emailOptional
emailLabelstringOptional
emailPdtFieldNamestringOptional
phonestringOptional

E.164 format

phoneLabelstringOptional
phonePdtFieldNamestringOptional
secondaryPhonestringOptional

E.164 format

secondaryPhoneLabelstringOptional
secondaryPhonePdtFieldNamestringOptional
pdtRecordIdstring · uuidRequired

Write-once — cannot be changed after creation.

relationstringRequired
activebooleanOptionalDefault: true
Responses
201

Contact created

application/json
idstring · uuidOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
createdBystring · uuid · nullableOptional
updatedBystring · uuid · nullableOptional
createdByNamestringOptional
updatedByNamestringOptional
namestringOptional
emailstring · email · nullableOptional
emailLabelstring · nullableOptional
emailPdtFieldNamestring · nullableOptional
phonestring · nullableOptional
phoneLabelstring · nullableOptional
phonePdtFieldNamestring · nullableOptional
secondaryPhonestring · nullableOptional
secondaryPhoneLabelstring · nullableOptional
secondaryPhonePdtFieldNamestring · nullableOptional
patientIdstring · uuidRead-onlyOptional
pdtRecordIdstring · uuidOptional
relationstringOptional
activebooleanOptional
post/{tenantName}/{instanceName}/patients/{patientId}/contacts
POST /{tenantName}/{instanceName}/patients/{patientId}/contacts HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 323

{
  "name": "text",
  "email": "name@gmail.com",
  "emailLabel": "text",
  "emailPdtFieldName": "text",
  "phone": "text",
  "phoneLabel": "text",
  "phonePdtFieldName": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhonePdtFieldName": "text",
  "pdtRecordId": "123e4567-e89b-12d3-a456-426614174000",
  "relation": "text",
  "active": true
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "updatedByName": "text",
  "name": "text",
  "email": "name@gmail.com",
  "emailLabel": "text",
  "emailPdtFieldName": "text",
  "phone": "text",
  "phoneLabel": "text",
  "phonePdtFieldName": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhonePdtFieldName": "text",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "pdtRecordId": "123e4567-e89b-12d3-a456-426614174000",
  "relation": "text",
  "active": true
}

Get Contact by ID

get

Description

This endpoint retrieves a specific contact associated with a particular patient. By making a GET request to this endpoint, you can retrieve detailed information about a specific contact based on the provided patient ID and contact ID.

Parameters

The endpoint requires the following parameters:

  • {{url}}: The base URL of the API.

  • {{tenantName}}: The name of the tenant or organization.

  • {{instanceName}}: The name of the specific instance within the tenant.

  • {{patientId}}: The unique identifier of the patient associated with the contact.

  • {{contactId}}: The unique identifier of the contact you wish to retrieve.

Request Headers

The following headers must be included in the request:

  • Authorization: A token or credentials to authenticate the request.

  • Content-Type: The format of the request payload, typically set to application/json.

Response

The response to a successful request will include the detailed information of the requested contact associated with the provided patient ID and contact ID.

Error Handling

If an error occurs, the response will include an appropriate HTTP status code along with an error message or code to indicate the specific issue encountered. Common error codes include 400 for bad requests, 401 for unauthorized access, and 404 for not found.

Authorization

Proper authorization credentials must be provided in the request headers to access this endpoint. Consult the API documentation or contact the system administrator to obtain the necessary authorization details.

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

contactIdstring · uuidRequired

UUID of the contact

Query parameters
pdtRecordIdstring · uuidOptionalExample: a76221fe-74ef-4915-8d24-31832144a457
activebooleanOptionalExample: false
Responses
200

Contact record

application/json
idstring · uuidOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
createdBystring · uuid · nullableOptional
updatedBystring · uuid · nullableOptional
createdByNamestringOptional
updatedByNamestringOptional
namestringOptional
emailstring · email · nullableOptional
emailLabelstring · nullableOptional
emailPdtFieldNamestring · nullableOptional
phonestring · nullableOptional
phoneLabelstring · nullableOptional
phonePdtFieldNamestring · nullableOptional
secondaryPhonestring · nullableOptional
secondaryPhoneLabelstring · nullableOptional
secondaryPhonePdtFieldNamestring · nullableOptional
patientIdstring · uuidRead-onlyOptional
pdtRecordIdstring · uuidOptional
relationstringOptional
activebooleanOptional
get/{tenantName}/{instanceName}/patients/{patientId}/contacts/{contactId}
GET /{tenantName}/{instanceName}/patients/{patientId}/contacts/{contactId} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "updatedByName": "text",
  "name": "text",
  "email": "name@gmail.com",
  "emailLabel": "text",
  "emailPdtFieldName": "text",
  "phone": "text",
  "phoneLabel": "text",
  "phonePdtFieldName": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhonePdtFieldName": "text",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "pdtRecordId": "123e4567-e89b-12d3-a456-426614174000",
  "relation": "text",
  "active": true
}

Update Contact

patch

Description

This endpoint allows you to update an existing contact associated with a specific patient. By making a PATCH request to this endpoint, you can modify the information of a specific contact based on the provided patient ID and contact ID.

Parameters

The endpoint requires the following parameters:

  • {{url}}: The base URL of the API.

  • {{tenantName}}: The name of the tenant or organization.

  • {{instanceName}}: The name of the specific instance within the tenant.

  • {{patientId}}: The unique identifier of the patient associated with the contact.

  • {{contactId}}: The unique identifier of the contact you wish to update.

Request Headers

The following headers must be included in the request:

  • Authorization: A token or credentials to authenticate the request.

  • Content-Type: The format of the request payload, typically set to application/json.

Request Body

The request body should contain the updated information for the contact. You can include any fields that need to be modified.

Response

The response to a successful request will include the updated contact object.

Error Handling

If an error occurs, the response will include an appropriate HTTP status code along with an error message or code to indicate the specific issue encountered. Common error codes include 400 for bad requests, 401 for unauthorized access, and 404 for not found.

Authorization

Proper authorization credentials must be provided in the request headers to access this endpoint. Consult the API documentation or contact the system administrator to obtain the necessary authorization details.

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

contactIdstring · uuidRequired

UUID of the contact

Body

Partial update. Note: pdtRecordId cannot be changed after creation.

namestringOptional
emailstring · emailOptional
emailLabelstringOptional
emailPdtFieldNamestringOptional
phonestringOptional

E.164 format

phoneLabelstringOptional
phonePdtFieldNamestringOptional
secondaryPhonestringOptional

E.164 format

secondaryPhoneLabelstringOptional
secondaryPhonePdtFieldNamestringOptional
relationstringOptional
activebooleanOptionalDefault: true
Responses
200

Updated contact

application/json
idstring · uuidOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
createdBystring · uuid · nullableOptional
updatedBystring · uuid · nullableOptional
createdByNamestringOptional
updatedByNamestringOptional
namestringOptional
emailstring · email · nullableOptional
emailLabelstring · nullableOptional
emailPdtFieldNamestring · nullableOptional
phonestring · nullableOptional
phoneLabelstring · nullableOptional
phonePdtFieldNamestring · nullableOptional
secondaryPhonestring · nullableOptional
secondaryPhoneLabelstring · nullableOptional
secondaryPhonePdtFieldNamestring · nullableOptional
patientIdstring · uuidRead-onlyOptional
pdtRecordIdstring · uuidOptional
relationstringOptional
activebooleanOptional
patch/{tenantName}/{instanceName}/patients/{patientId}/contacts/{contactId}
PATCH /{tenantName}/{instanceName}/patients/{patientId}/contacts/{contactId} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 270

{
  "name": "text",
  "email": "name@gmail.com",
  "emailLabel": "text",
  "emailPdtFieldName": "text",
  "phone": "text",
  "phoneLabel": "text",
  "phonePdtFieldName": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhonePdtFieldName": "text",
  "relation": "text",
  "active": true
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "updatedByName": "text",
  "name": "text",
  "email": "name@gmail.com",
  "emailLabel": "text",
  "emailPdtFieldName": "text",
  "phone": "text",
  "phoneLabel": "text",
  "phonePdtFieldName": "text",
  "secondaryPhone": "text",
  "secondaryPhoneLabel": "text",
  "secondaryPhonePdtFieldName": "text",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "pdtRecordId": "123e4567-e89b-12d3-a456-426614174000",
  "relation": "text",
  "active": true
}
PreviousPatient
NextCustom Data Types (CDT) Formation

Last updated

Was this helpful?