Encounters

The "Encounters" folder in the API collection houses a curated selection of API requests and endpoints that pertain to managing and tracking patient encounters. Encounters refer to the interactions, appointments, or medical events between healthcare professionals and patients. This folder organizes the necessary API calls for creating, retrieving, updating, and deleting encounter records, streamlining the testing and development of functionalities related to patient interactions within the API collection.

Get all Encounter Records by user ID

get

HTTP Request

GET /{tenantName}/{instanceName}/users/{userId}/encounters

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/users/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

userIdstring · uuidRequired

UUID of the user

Query parameters

pageintegerOptional

Pagination: page number

Default: 0Example: 0

sizeintegerOptional

Pagination: page size

Default: 20Example: 50

sortstringOptional

Sort field with sorting order(asc or desc) after coma

Example: status%2CcalendarEventStartDatetime%2Casc

statusesstring[]Optional

Encounter status. Available statuses: DRAFT,OPEN,ACTIVE,FINALIZED

Example: ["OPEN","DRAFT","FINALIZED","CANCELLED"]

withCareTeambooleanOptional

If true, return only encounter thats belong to the patients in the user care team (default: true)

Example: true

Responses

200

Paginated encounter records

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/users/{userId}/encounters

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

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "cdtId": "123e4567-e89b-12d3-a456-426614174000",
      "version": 1,
      "cdtName": "text",
      "jsonBody": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "metaInfo": {
    "page": 1,
    "pageSize": 1,
    "totalElements": 1,
    "numberOfElements": 1
  }
}

Get all Encounter Records by patient ID

get

HTTP Request

GET /{tenantName}/{instanceName}/patients/{patientId}/encounters

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

statusesstring[]Optional

Encounter status. Available statuses: DRAFT,OPEN,ACTIVE,FINALIZED

pageintegerOptional

Pagination: page number

Default: 0

sizeintegerOptional

Pagination: page size

Default: 20

sortstringOptional

Sort field with sorting order(asc or desc) after coma

onlyWithCalendarEventbooleanOptional

Exclude all information not related to calendar event, except encounter record

Responses

200

Paginated encounter records

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

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

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

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "cdtId": "123e4567-e89b-12d3-a456-426614174000",
      "version": 1,
      "cdtName": "text",
      "jsonBody": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "metaInfo": {
    "page": 1,
    "pageSize": 1,
    "totalElements": 1,
    "numberOfElements": 1
  }
}

Create an Encounter for Patient

post

This endpoint allows you to create a new encounter record for a specific patient.

{{url}}/{{tenantName}}/{{instanceName}}/patients/{{patientId}}/encounters

Some information about the parameter location:

For creating encounters via API this parameter is a string.

After creating an encounter via API, on the UI this string is displayed depending on the eventMode:

- IN-PERSON: Тhe location value is displayed as text that can be copied.

- CALL: You need to enter the patient number, and then the location value is displayed as a link, when clicked on, it opens the call drover in the patient's commcenter. The link will be displayed as an encounter location if the patient has a primary phone number specified

- VIDEO: the location value is displayed as an external link. The link must be fully specified

To fill in the billing information, the responsibleParty parameters and information about services should be passed into the body of the request. responsibleParty ('Billing Type' on UI) can take values:

• SELF_PAY
• INSURANCE

In the visitServices block you should pass all the services that should be attached to this encounter.

• name - the name of the service, which is specified in the designer
• preVisitCost ('Co-pay' on UI) and serviceCost ('Fee' on UI) - payment amount, it is specified in cents.
• modifiers - list of modifiers for this service, the names are specified in the designer. Service can be without modifiers

HTTP Response Codes:

• 201: Successfully created the encounter for the 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

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

calendarEventIdstring · uuid · nullableOptional

titlestringRequired

descriptionstring · nullableOptional

instructionstring · nullableOptional

colorstring · nullableOptional

statusstring · enumOptionalDefault: DRAFTPossible values:

templateNamestring · nullableOptional

notesstring · nullableOptional

timezonestring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

locationstring · nullableOptional

Responses

201

Created encounter

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

post/{tenantName}/{instanceName}/patients/{patientId}/encounters

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

{
  "calendarEventId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "instruction": "text",
  "color": "text",
  "status": "DRAFT",
  "templateName": "text",
  "notes": "text",
  "patientInfo": {
    "patientId": "123e4567-e89b-12d3-a456-426614174000",
    "firstName": "text",
    "lastName": "text"
  },
  "timezone": "text",
  "visitServices": [
    {
      "name": "text",
      "quantity": 1,
      "serviceCost": 1,
      "cancellationFee": 1,
      "preVisitCost": 1,
      "modifiers": [
        "text"
      ]
    }
  ],
  "encounterPaymentInfo": {
    "status": "NO_PAYMENT_DUE",
    "amountDue": 1,
    "lastUpdatedAt": 1
  },
  "location": "text",
  "currentScheduledAppointment": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get all Encounter Records by client_id from JWT Token (work for users and api_clients tokens)

get

HTTP Request

For receiving this list as an API client need to set param withCareTeam=false. Example: {{ url }} / {{ tenantName }} / {{ instanceName }} /encounters**?withCareTeam=false**

GET /{tenantName}/{instanceName}/encounters

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/encounters

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

Query parameters

pageintegerOptional

Zero-based page number

Default: 0

sizeinteger · min: 1 · max: 1000Optional

Number of results per page

Default: 20

sortstringOptional

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

statusesstring[]Optional

Encounter status. Available statuses: DRAFT,OPEN,ACTIVE,FINALIZED

Responses

200

Paginated encounter records for the current API client

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/encounters

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

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "cdtId": "123e4567-e89b-12d3-a456-426614174000",
      "version": 1,
      "cdtName": "text",
      "jsonBody": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "metaInfo": {
    "page": 1,
    "pageSize": 1,
    "totalElements": 1,
    "numberOfElements": 1
  }
}

Get all Encounter Records with related data by client_id from JWT Token (work for users and api_clients tokens)

get

HTTP Request

GET /{tenantName}/{instanceName}/full-encounters

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/full-encounters

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

Query parameters

filtersstringOptionalExample: activeUserId={{userId}}

createdBystringOptionalExample: {{userId}}

onlyWithCalendarEventbooleanOptional

Exclude all information not related to calendar event, except encounter record

Example: false

statusesstring[]Optional

Encounter status. Available statuses: DRAFT,OPEN,ACTIVE,FINALIZED

pageintegerOptional

Pagination: page number

Default: 0

sizeintegerOptional

Pagination: page size

Default: 20

sortstringOptional

Sort field with sorting order(asc or desc) after coma

Responses

200

Paginated full encounter records

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/full-encounters

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

{
  "data": [
    {
      "encounter": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "patientId": "123e4567-e89b-12d3-a456-426614174000",
        "cdtId": "123e4567-e89b-12d3-a456-426614174000",
        "version": 1,
        "cdtName": "text",
        "jsonBody": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "disposition": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "patientId": "123e4567-e89b-12d3-a456-426614174000",
        "cdtId": "123e4567-e89b-12d3-a456-426614174000",
        "version": 1,
        "cdtName": "text",
        "jsonBody": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "calendarEvent": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "userRelatedToCalendarEvent": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "assessmentLinks": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "patientId": "123e4567-e89b-12d3-a456-426614174000",
          "cdtId": "123e4567-e89b-12d3-a456-426614174000",
          "version": 1,
          "cdtName": "text",
          "jsonBody": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ],
      "comments": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z",
          "createdByName": "text",
          "updatedByName": "text",
          "encounterId": "123e4567-e89b-12d3-a456-426614174000",
          "text": "text"
        }
      ]
    }
  ],
  "metaInfo": {
    "page": 1,
    "pageSize": 1,
    "totalElements": 1,
    "numberOfElements": 1
  }
}

Get all Encounter Records with related data by patient ID

get

Get all encounter records with related data by patient id

HTTP Request

GET /{tenantName}/{instanceName}/patients/{patientId}/full-encounters

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/patients/08632f11-cb33-4b5b-aece-aaa360f9f747/full-encounters

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

statusesstring[]Optional

Encounter status. Available statuses: DRAFT,OPEN,ACTIVE,FINALIZED

Example: ["OPEN"]

pageintegerOptional

Pagination: page number

Default: 0Example: 1

sizeintegerOptional

Pagination: page size

Default: 20Example: 1

sortstringOptional

Sort field with sorting order(asc or desc) after coma

Example: updatedAt,desc

sortByCalendarstringOptional

ASC,DESC

Example: ASC

onlyWithCalendarEventbooleanOptional

Exclude all information not related to calendar event, except encounter record

Example: true

Responses

200

Paginated full encounter records

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}/full-encounters

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

{
  "data": [
    {
      "encounter": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "patientId": "123e4567-e89b-12d3-a456-426614174000",
        "cdtId": "123e4567-e89b-12d3-a456-426614174000",
        "version": 1,
        "cdtName": "text",
        "jsonBody": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "disposition": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "patientId": "123e4567-e89b-12d3-a456-426614174000",
        "cdtId": "123e4567-e89b-12d3-a456-426614174000",
        "version": 1,
        "cdtName": "text",
        "jsonBody": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "calendarEvent": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "userRelatedToCalendarEvent": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "assessmentLinks": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "patientId": "123e4567-e89b-12d3-a456-426614174000",
          "cdtId": "123e4567-e89b-12d3-a456-426614174000",
          "version": 1,
          "cdtName": "text",
          "jsonBody": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ],
      "comments": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z",
          "createdByName": "text",
          "updatedByName": "text",
          "encounterId": "123e4567-e89b-12d3-a456-426614174000",
          "text": "text"
        }
      ]
    }
  ],
  "metaInfo": {
    "page": 1,
    "pageSize": 1,
    "totalElements": 1,
    "numberOfElements": 1
  }
}

Get all Encounter Records with related data by user ID

get

HTTP Request

GET /{tenantName}/{instanceName}/users/{userId}/full-encounters

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/users/f5b84d92-7989-45f4-bb5f-d85336c8e4b6/full-encounters

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

userIdstring · uuidRequired

UUID of the user

Query parameters

filtersstringOptionalExample: ownerUserId={{userId}}

onlyWithCalendarEventbooleanOptional

Exclude all information not related to calendar event, except encounter record

Example: true

calendarEventFromstringOptionalExample: 2021-09-30T21%3A00%3A00.000Z

calendarEventTostringOptionalExample: 2021-10-31T20%3A59%3A59.999Z

createdBystringOptionalExample: {{userId}}

withCareTeambooleanOptional

If true, return only encounter thats belong to the patients in the user care team (default: true)

Example: false

statusesstring[]Optional

Encounter status. Available statuses: DRAFT,OPEN,ACTIVE,FINALIZED

pageintegerOptional

Pagination: page number

Default: 0

sizeintegerOptional

Pagination: page size

Default: 20

sortstringOptional

Sort field with sorting order(asc or desc) after coma

Responses

200

Paginated full encounter records

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/users/{userId}/full-encounters

GET /{tenantName}/{instanceName}/users/{userId}/full-encounters HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "encounter": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "patientId": "123e4567-e89b-12d3-a456-426614174000",
        "cdtId": "123e4567-e89b-12d3-a456-426614174000",
        "version": 1,
        "cdtName": "text",
        "jsonBody": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "disposition": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "patientId": "123e4567-e89b-12d3-a456-426614174000",
        "cdtId": "123e4567-e89b-12d3-a456-426614174000",
        "version": 1,
        "cdtName": "text",
        "jsonBody": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "calendarEvent": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "userRelatedToCalendarEvent": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "assessmentLinks": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "patientId": "123e4567-e89b-12d3-a456-426614174000",
          "cdtId": "123e4567-e89b-12d3-a456-426614174000",
          "version": 1,
          "cdtName": "text",
          "jsonBody": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ],
      "comments": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z",
          "createdByName": "text",
          "updatedByName": "text",
          "encounterId": "123e4567-e89b-12d3-a456-426614174000",
          "text": "text"
        }
      ]
    }
  ],
  "metaInfo": {
    "page": 1,
    "pageSize": 1,
    "totalElements": 1,
    "numberOfElements": 1
  }
}

Get Encounter Record by a patient ID and Encounter ID

get

HTTP Request

GET /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82

Responses

The encounter information will come as a response. The startDateTime (endDateTime) and the same variables will be displayed for the encaunter, but for local time localStartDateTime (localEndDateTime).

• startDateTime/endDateTime - start and end times in UTCs
• localStartDateTime/localEndDateTime - information about the local time for the user who is requesting the information (When information is requested using an API request, the request is made from under the API client, it has no timezone and therefore the information is displayed in the UTC).

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

Responses

200

Encounter record

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

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

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Update Encounter Record by Encounter ID

patch

HTTP Request

Please, fill only that fields that you want to update.

Correspondence of Encounter statuses for the GUI:

DRAFT - Planned on UI OPEN - In Progress on UI CANCELLED - Cancelled on UI FINALIZED - Completed on UI

PATCH /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}

in our example it would be:

PATCH https://api.live.welkincloud.io/gh/sb-demo/patients/620ef7f0-2ba9-48e1-8e0f-a47f40890bf4/encounters/b30355dd-ff65-4ae3-aab7-a1bdd0fddd79

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

Body

Partial update — all fields optional.

calendarEventIdstring · uuid · nullableOptional

titlestringOptional

descriptionstring · nullableOptional

statusstring · enumOptionalPossible values:

notesstring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

locationstring · nullableOptional

Responses

200

Updated encounter

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

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

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

{
  "calendarEventId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "DRAFT",
  "notes": "text",
  "location": "text",
  "visitServices": [
    {
      "name": "text",
      "quantity": 1,
      "serviceCost": 1,
      "cancellationFee": 1,
      "preVisitCost": 1,
      "modifiers": [
        "text"
      ]
    }
  ],
  "currentScheduledAppointment": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Encounter Record with all related data by a patient ID and encounter ID

get

HTTP Request

GET /{tenantName}/{instanceName}/patients/{patientId}/full-encounters/{encounterId}

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/patients/08632f11-cb33-4b5b-aece-aaa360f9f747/full-encounters/7d72c423-48bc-4fc6-aa35-72a6cdd0c4ca

Responses

The encounter information will come as a response. The startDateTime (endDateTime) and the same variables will be displayed for the encaunter, but for local time localStartDateTime (localEndDateTime).

• startDateTime/endDateTime - start and end times in UTCs
• localStartDateTime/localEndDateTime - information about the local time for the user who is requesting the information (When information is requested using an API request, the request is made from under the API client, it has no timezone and therefore the information is displayed in the UTC).

Translated with DeepL.com (free version)

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

Responses

200

Full encounter record

application/json

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}/full-encounters/{encounterId}

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

{
  "encounter": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "patientId": "123e4567-e89b-12d3-a456-426614174000",
    "cdtId": "123e4567-e89b-12d3-a456-426614174000",
    "version": 1,
    "cdtName": "text",
    "jsonBody": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "disposition": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "patientId": "123e4567-e89b-12d3-a456-426614174000",
    "cdtId": "123e4567-e89b-12d3-a456-426614174000",
    "version": 1,
    "cdtName": "text",
    "jsonBody": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "calendarEvent": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "userRelatedToCalendarEvent": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "assessmentLinks": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "patientId": "123e4567-e89b-12d3-a456-426614174000",
      "cdtId": "123e4567-e89b-12d3-a456-426614174000",
      "version": 1,
      "cdtName": "text",
      "jsonBody": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "comments": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "createdByName": "text",
      "updatedByName": "text",
      "encounterId": "123e4567-e89b-12d3-a456-426614174000",
      "text": "text"
    }
  ]
}

Get all Assessment links by encounter ID

get

HTTP Request

GET /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82/assessments

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

Query parameters

relationstringOptionalExample: COMMON

Responses

200

Assessment links for this encounter

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments

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

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "patientId": "123e4567-e89b-12d3-a456-426614174000",
    "cdtId": "123e4567-e89b-12d3-a456-426614174000",
    "version": 1,
    "cdtName": "text",
    "jsonBody": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Create an Assessment link for encounter

post

HTTP Request

POST /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments

in our example it would be:

POST https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82/assessments

Responses

Code	Description
201	Created
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

Body

assessmentNamestringRequired

assessmentTitlestring · nullableOptional

assessmentRecordIdstring · uuid · nullableOptional

Responses

201

Created assessment link

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

post/{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments

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

{
  "assessmentName": "text",
  "assessmentTitle": "text",
  "assessmentRecordId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Assessment link by encounter ID and assessment link ID

get

HTTP Request

GET /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments/{encounterAssessmentId}

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82/assessments/0e692ed3-b250-42ee-a17b-f65e69efcc07

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

encounterAssessmentIdstring · uuidRequired

encounterAssessmentId path parameter

Responses

200

Assessment link

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments/{encounterAssessmentId}

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Delete Assessment link for encounter by assessment link ID

delete

HTTP Request

DELETE /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments/{encounterAssessmentId}

in our example it would be:

DELETE https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82/assessments/0e692ed3-b250-42ee-a17b-f65e69efcc07

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

encounterAssessmentIdstring · uuidRequired

encounterAssessmentId path parameter

Responses

200

Assessment link deleted

No content

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

delete/{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments/{encounterAssessmentId}

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

No content

Update Assessment link for encounter by assessment link ID

patch

HTTP Request

PATCH /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments/{encounterAssessmentId}

in our example it would be:

PATCH https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82/assessments/0e692ed3-b250-42ee-a17b-f65e69efcc07

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

encounterAssessmentIdstring · uuidRequired

encounterAssessmentId path parameter

Body

assessmentRecordIdstring · uuidRequired

Responses

200

Updated assessment link

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

patch/{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/assessments/{encounterAssessmentId}

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

{
  "assessmentRecordId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Disposition for encounter

get

HTTP Request

GET /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/disposition

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82/disposition

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

Responses

200

Disposition record

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/disposition

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Update Disposition for encounter

patch

HTTP Request

PATCH /{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/disposition

in our example it would be:

PATCH https://api.live.welkincloud.io/gh/sb-demo/patients/d6ea79ce-d3d6-4c2d-a27e-e4d1207f60f1/encounters/336ae731-c674-4b85-941a-ef3b37d93b82/disposition

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterIdstring · uuidRequired

UUID of the encounter

Body

Field values as defined by the disposition CDT formation — there is no fixed schema.

Other propertiesanyOptional

Responses

200

Updated disposition record

application/json

idstring · uuidOptional

patientIdstring · uuidOptional

cdtIdstring · uuidOptional

versionintegerOptional

cdtNamestringOptional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

patch/{tenantName}/{instanceName}/patients/{patientId}/encounters/{encounterId}/disposition

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

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "cdtId": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "cdtName": "text",
  "jsonBody": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Disposition Formation

get

Request to Get current encounter billing formation:

HTTP Request

GET /{tenantName}/{instanceName}/formations/{version}/encounter-disposition

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/formations/current/encounter-disposition

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

Responses

200

Disposition CDT formation

application/json

idstring · uuidOptional

namestringRequiredPattern: ^[a-z0-9\-_]+$

titlestringOptional

labelstringOptional

versionintegerOptional

internalbooleanOptional

readablebooleanOptionalDefault: true

updatablebooleanOptionalDefault: true

typestring · enumOptionalPossible values:

relationstring · enumOptionalPossible values:

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/formations/current/encounter-disposition

GET /{tenantName}/{instanceName}/formations/current/encounter-disposition HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "title": "text",
  "label": "text",
  "version": 1,
  "internal": true,
  "readable": true,
  "updatable": true,
  "type": "SINGLE_RECORD",
  "relation": "COMMON",
  "fields": [
    {
      "name": "text",
      "type": "TEXT",
      "formula": "text",
      "dictionary": {
        "name": "text",
        "field": "text"
      },
      "profileDataType": {
        "name": "text",
        "fields": [
          "text"
        ]
      },
      "customDataType": {
        "name": "text",
        "fields": [
          "text"
        ]
      },
      "customFieldType": "text",
      "editable": true,
      "searchable": true,
      "bulkEdit": true,
      "phi": true,
      "disable": true,
      "injectedSource": true,
      "displayType": "CHECKBOX",
      "valueType": "STRING",
      "meta": {
        "label": "text",
        "minLength": 1,
        "maxLength": 1,
        "minValue": "text",
        "maxValue": "text",
        "fileTypes": [
          "text"
        ],
        "maxFiles": 1,
        "maxTotalFileSize": 1,
        "required": true,
        "options": [
          {
            "label": "text",
            "value": null,
            "refCdtName": "text"
          }
        ],
        "multiple": true,
        "patterns": [
          "NUMBERS_ONLY"
        ]
      },
      "mask": {
        "symbol": "*",
        "startPosition": 1,
        "endPosition": 1
      },
      "richTextEnabled": true
    }
  ]
}

Get all Encounter Templates

get

Request to Get all encounter templates with filter.

HTTP Request

GET /{tenantName}/{instanceName}/formations/{version}/encounters

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/formations/current/encounters

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

versionstringRequired

Formation version identifier (e.g. current, draft, or a version number)

Example: current

Query parameters

searchstringOptional

name or type

Example: Cust

Responses

200

List of encounter templates

application/json

idstring · uuidRead-onlyOptional

namestringRequiredPattern: ^[a-z0-9\-_]+$

titlestringOptional

encounterDescriptionstring · nullableOptional

encounterInstructionstring · nullableOptional

encounterColorstring · nullableOptional

typestring · nullableOptional

deliveryMethodstringRequired

defaultDurationinteger · nullableOptional

Minutes

acuityAppointmentTypeIdstring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

predefinedLocationstring · nullableOptional

assessmentNamesstring[]Optional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/formations/{version}/encounters

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

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "title": "text",
    "encounterDescription": "text",
    "encounterInstruction": "text",
    "encounterColor": "text",
    "type": "text",
    "deliveryMethod": "text",
    "defaultDuration": 1,
    "acuityAppointmentTypeId": "text",
    "locationPdtSource": {
      "name": "text",
      "fields": [
        "text"
      ]
    },
    "predefinedLocation": "text",
    "assessmentNames": [
      "text"
    ],
    "visitServices": [
      {
        "name": "text",
        "modifiers": [
          "text"
        ]
      }
    ]
  }
]

Get Encounter Template by name

get

Request to Get one encounter template by name.

HTTP Request

GET /{tenantName}/{instanceName}/formations/{version}/encounters/{encounterTemplateName}

in our example it would be:

GET https://api.live.welkincloud.io/gh/sb-demo/formations/current/encounters/temp-1

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

versionstringRequired

Formation version identifier (e.g. current, draft, or a version number)

Example: current

encounterTemplateNamestringRequired

encounterTemplateName path parameter

Responses

200

Encounter template

application/json

idstring · uuidRead-onlyOptional

namestringRequiredPattern: ^[a-z0-9\-_]+$

titlestringOptional

encounterDescriptionstring · nullableOptional

encounterInstructionstring · nullableOptional

encounterColorstring · nullableOptional

typestring · nullableOptional

deliveryMethodstringRequired

defaultDurationinteger · nullableOptional

Minutes

acuityAppointmentTypeIdstring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

predefinedLocationstring · nullableOptional

assessmentNamesstring[]Optional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

get/{tenantName}/{instanceName}/formations/{version}/encounters/{encounterTemplateName}

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "title": "text",
  "encounterDescription": "text",
  "encounterInstruction": "text",
  "encounterColor": "text",
  "type": "text",
  "deliveryMethod": "text",
  "defaultDuration": 1,
  "acuityAppointmentTypeId": "text",
  "locationPdtSource": {
    "name": "text",
    "fields": [
      "text"
    ]
  },
  "predefinedLocation": "text",
  "assessmentNames": [
    "text"
  ],
  "visitServices": [
    {
      "name": "text",
      "modifiers": [
        "text"
      ]
    }
  ]
}

Create a Template for encounter

post

Request to Create new encounter template.

HTTP Request

POST /{tenantName}/{instanceName}/formations/draft/encounters

in our example it would be:

POST https://api.live.welkincloud.io/gh/sb-demo/formations/draft/encounters

Responses

Code	Description
201	Created
401	Unauthorized
403	Forbidden
404	Not Found

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

Body

idstring · uuidRead-onlyOptional

namestringRequiredPattern: ^[a-z0-9\-_]+$

titlestringOptional

encounterDescriptionstring · nullableOptional

encounterInstructionstring · nullableOptional

encounterColorstring · nullableOptional

typestring · nullableOptional

deliveryMethodstringRequired

defaultDurationinteger · nullableOptional

Minutes

acuityAppointmentTypeIdstring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

predefinedLocationstring · nullableOptional

assessmentNamesstring[]Optional

Responses

201

Created encounter template

application/json

idstring · uuidRead-onlyOptional

namestringRequiredPattern: ^[a-z0-9\-_]+$

titlestringOptional

encounterDescriptionstring · nullableOptional

encounterInstructionstring · nullableOptional

encounterColorstring · nullableOptional

typestring · nullableOptional

deliveryMethodstringRequired

defaultDurationinteger · nullableOptional

Minutes

acuityAppointmentTypeIdstring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

predefinedLocationstring · nullableOptional

assessmentNamesstring[]Optional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

post/{tenantName}/{instanceName}/formations/draft/encounters

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

{
  "name": "text",
  "title": "text",
  "encounterDescription": "text",
  "encounterInstruction": "text",
  "encounterColor": "text",
  "type": "text",
  "deliveryMethod": "text",
  "defaultDuration": 1,
  "acuityAppointmentTypeId": "text",
  "locationPdtSource": {
    "name": "text",
    "fields": [
      "text"
    ]
  },
  "predefinedLocation": "text",
  "assessmentNames": [
    "text"
  ],
  "visitServices": [
    {
      "name": "text",
      "modifiers": [
        "text"
      ]
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "title": "text",
  "encounterDescription": "text",
  "encounterInstruction": "text",
  "encounterColor": "text",
  "type": "text",
  "deliveryMethod": "text",
  "defaultDuration": 1,
  "acuityAppointmentTypeId": "text",
  "locationPdtSource": {
    "name": "text",
    "fields": [
      "text"
    ]
  },
  "predefinedLocation": "text",
  "assessmentNames": [
    "text"
  ],
  "visitServices": [
    {
      "name": "text",
      "modifiers": [
        "text"
      ]
    }
  ]
}

Update Encounter Template by encounter template name

put

Full update encounter template.

PUT /{tenantName}/{instanceName}/formations/draft/encounters/{encounterTemplateName}

in our example it would be:

PUT https://api.live.welkincloud.io/gh/sb-demo/formations/draft/encounters/temp-1

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

Authorizations

AuthorizationstringRequired

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

Path parameters

tenantNamestringRequired

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

Example: acme-health

instanceNamestringRequired

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

Example: live

Body

idstring · uuidRead-onlyOptional

namestringRequiredPattern: ^[a-z0-9\-_]+$

titlestringOptional

encounterDescriptionstring · nullableOptional

encounterInstructionstring · nullableOptional

encounterColorstring · nullableOptional

typestring · nullableOptional

deliveryMethodstringRequired

defaultDurationinteger · nullableOptional

Minutes

acuityAppointmentTypeIdstring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

predefinedLocationstring · nullableOptional

assessmentNamesstring[]Optional

Responses

200

Updated encounter template

application/json

idstring · uuidRead-onlyOptional

namestringRequiredPattern: ^[a-z0-9\-_]+$

titlestringOptional

encounterDescriptionstring · nullableOptional

encounterInstructionstring · nullableOptional

encounterColorstring · nullableOptional

typestring · nullableOptional

deliveryMethodstringRequired

defaultDurationinteger · nullableOptional

Minutes

acuityAppointmentTypeIdstring · nullableOptional

responsiblePartystring · enumOptionalDeprecatedPossible values:

predefinedLocationstring · nullableOptional

assessmentNamesstring[]Optional

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

put/{tenantName}/{instanceName}/formations/draft/encounters/etmp-master

PUT /{tenantName}/{instanceName}/formations/draft/encounters/etmp-master HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 369

{
  "name": "text",
  "title": "text",
  "encounterDescription": "text",
  "encounterInstruction": "text",
  "encounterColor": "text",
  "type": "text",
  "deliveryMethod": "text",
  "defaultDuration": 1,
  "acuityAppointmentTypeId": "text",
  "locationPdtSource": {
    "name": "text",
    "fields": [
      "text"
    ]
  },
  "predefinedLocation": "text",
  "assessmentNames": [
    "text"
  ],
  "visitServices": [
    {
      "name": "text",
      "modifiers": [
        "text"
      ]
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "title": "text",
  "encounterDescription": "text",
  "encounterInstruction": "text",
  "encounterColor": "text",
  "type": "text",
  "deliveryMethod": "text",
  "defaultDuration": 1,
  "acuityAppointmentTypeId": "text",
  "locationPdtSource": {
    "name": "text",
    "fields": [
      "text"
    ]
  },
  "predefinedLocation": "text",
  "assessmentNames": [
    "text"
  ],
  "visitServices": [
    {
      "name": "text",
      "modifiers": [
        "text"
      ]
    }
  ]
}

Delete Encounter Template by template name

delete

Delete encounter template by name

HTTP Request

DELETE /{tenantName}/{instanceName}/formations/draft/encounters/{encounterTemplateName}

in our example it would be:

DELETE https://api.live.welkincloud.io/gh/sb-demo/formations/draft/encounters/336ae731-c674-4b85-941a-ef3b37d93b82

Responses

Code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

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

encounterTemplateNamestringRequired

encounterTemplateName path parameter

Responses

200

Encounter template deleted

No content

400

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

401

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

403

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

404

Not found — the requested resource does not exist.

429

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

500

Internal server error.

delete/{tenantName}/{instanceName}/formations/draft/encounters/{encounterTemplateName}

DELETE /{tenantName}/{instanceName}/formations/draft/encounters/{encounterTemplateName} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content