Patient Program

Get Patient's Program by name (for active only)

get

HTTP Request

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

in our example it would be:

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

Responses

Code

Description

200

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

prog_namestringRequired

prog_name path parameter

Query parameters

assignedProgramsbooleanOptional

Assigned or unassigned programs

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

Active patient program

application/json

idstring · uuidOptional

createdByNamestringOptional

createdAtstring · date-timeOptional

updatedByNamestringOptional

updatedAtstring · date-timeOptional

programNamestringOptional

programTitlestringOptional

programDescriptionstring · nullableOptional

assignedbooleanOptionalDefault: true

patientIdstring · uuidOptional

statusstring · enumOptionalPossible values:

compatibleWithCurrentVersionbooleanOptional

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}/programs/current/{prog_name}

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedByName": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "programName": "text",
  "programTitle": "text",
  "programDescription": "text",
  "assigned": true,
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "currentPhase": {
    "timestamp": "2026-01-01T00:00:00.000Z",
    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
    "createdByName": "text",
    "name": "text",
    "title": "text",
    "description": "text",
    "currentVersion": "text",
    "deleted": true
  },
  "status": "NOT_STARTED",
  "compatibleWithCurrentVersion": true,
  "pathHistory": [
    {
      "timestamp": "2026-01-01T00:00:00.000Z",
      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "currentVersion": "text",
      "deleted": true
    }
  ]
}

Get Patient's Program by ID (active and finished)

get

HTTP Request

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

in our example it would be:

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

Responses

Code

Description

200

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

prog_idstring · uuidRequired

prog_id path parameter

Query parameters

assignedProgramsbooleanOptional

Assigned or unassigned programs

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

Patient program enrollment record (active or finished)

application/json

idstring · uuidOptional

createdByNamestringOptional

createdAtstring · date-timeOptional

updatedByNamestringOptional

updatedAtstring · date-timeOptional

programNamestringOptional

programTitlestringOptional

programDescriptionstring · nullableOptional

assignedbooleanOptionalDefault: true

patientIdstring · uuidOptional

statusstring · enumOptionalPossible values:

compatibleWithCurrentVersionbooleanOptional

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}/programs/history/{prog_id}

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedByName": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "programName": "text",
  "programTitle": "text",
  "programDescription": "text",
  "assigned": true,
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "currentPhase": {
    "timestamp": "2026-01-01T00:00:00.000Z",
    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
    "createdByName": "text",
    "name": "text",
    "title": "text",
    "description": "text",
    "currentVersion": "text",
    "deleted": true
  },
  "status": "NOT_STARTED",
  "compatibleWithCurrentVersion": true,
  "pathHistory": [
    {
      "timestamp": "2026-01-01T00:00:00.000Z",
      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "currentVersion": "text",
      "deleted": true
    }
  ]
}

Unassign Patient from Program

delete

HTTP Request

DELETE /{tenantName}/{instanceName}/patients/{patientId}/programs/{programId}

in our example it would be:

DELETE https://api.live.welkincloud.io/gh/sb-demo/patients/08632f11-cb33-4b5b-aece-aaa360f9f747/programs/11132f11-cb33-4b5b-aece-abc125fed987

Responses

Code

Description

200

401

Unauthorized

403

Forbidden

404

Not Found

Note: the backend resolves this by patient-program enrollment ID, not by program name — confirm the exact identifier your gateway expects before relying on this path shape.

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

programNamestringRequired

Machine-readable program name

Responses

200

Patient unassigned from program

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}/programs/{programName}

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

No content

Update Patient Program status and assign Program

patch

HTTP Request

PATCH /{tenantName}/{instanceName}/patients/{patientId}/programs/{programName}

in our example it would be:

PATCH https://api.live.welkincloud.io/gh/sb-demo/patients/08632f11-cb33-4b5b-aece-aaa360f9f747/programs/prog-4

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

programNamestringRequired

Machine-readable program name

Body

statusstring · enumOptionalPossible values:

assignedbooleanOptional

phaseNamestringOptional

Responses

200

Updated patient program

application/json

idstring · uuidOptional

createdByNamestringOptional

createdAtstring · date-timeOptional

updatedByNamestringOptional

updatedAtstring · date-timeOptional

programNamestringOptional

programTitlestringOptional

programDescriptionstring · nullableOptional

assignedbooleanOptionalDefault: true

patientIdstring · uuidOptional

statusstring · enumOptionalPossible values:

compatibleWithCurrentVersionbooleanOptional

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}/programs/{programName}

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

{
  "status": "NOT_STARTED",
  "assigned": true,
  "phaseName": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedByName": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "programName": "text",
  "programTitle": "text",
  "programDescription": "text",
  "assigned": true,
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "currentPhase": {
    "timestamp": "2026-01-01T00:00:00.000Z",
    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
    "createdByName": "text",
    "name": "text",
    "title": "text",
    "description": "text",
    "currentVersion": "text",
    "deleted": true
  },
  "status": "NOT_STARTED",
  "compatibleWithCurrentVersion": true,
  "pathHistory": [
    {
      "timestamp": "2026-01-01T00:00:00.000Z",
      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "currentVersion": "text",
      "deleted": true
    }
  ]
}

Change Phase for Patient Program

patch

HTTP Request

PATCH /{tenantName}/{instanceName}/patients/{patientId}/programs/{programName}/phases

in our example it would be:

PATCH https://api.live.welkincloud.io/gh/sb-demo/patients/08632f11-cb33-4b5b-aece-aaa360f9f747/programs/lead-management-program/phases

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

programNamestringRequired

Machine-readable program name

Body

phaseNamestringRequired

Responses

200

Updated patient program after phase change

application/json

idstring · uuidOptional

createdByNamestringOptional

createdAtstring · date-timeOptional

updatedByNamestringOptional

updatedAtstring · date-timeOptional

programNamestringOptional

programTitlestringOptional

programDescriptionstring · nullableOptional

assignedbooleanOptionalDefault: true

patientIdstring · uuidOptional

statusstring · enumOptionalPossible values:

compatibleWithCurrentVersionbooleanOptional

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}/programs/{programName}/phases

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

{
  "phaseName": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdByName": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedByName": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "programName": "text",
  "programTitle": "text",
  "programDescription": "text",
  "assigned": true,
  "patientId": "123e4567-e89b-12d3-a456-426614174000",
  "currentPhase": {
    "timestamp": "2026-01-01T00:00:00.000Z",
    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
    "createdByName": "text",
    "name": "text",
    "title": "text",
    "description": "text",
    "currentVersion": "text",
    "deleted": true
  },
  "status": "NOT_STARTED",
  "compatibleWithCurrentVersion": true,
  "pathHistory": [
    {
      "timestamp": "2026-01-01T00:00:00.000Z",
      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
      "createdByName": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "currentVersion": "text",
      "deleted": true
    }
  ]
}

PreviousTask Management

NextDictionaries

Last updated 18 days ago

Was this helpful?