Core Concepts
Understanding Welkin's data model and API design will help you build integrations faster and avoid common mistakes. This page covers the fundamental building blocks every developer should know before making API calls.
Tenants
Every Welkin customer is provisioned as a tenant — an isolated environment with its own data, configuration, and users. All API endpoints are scoped to a tenant:
https://api.welkinhealth.com/v1/{tenant}/Your tenant identifier is provided during onboarding. Most organizations have two tenants: one for staging (-sandbox) and one for production.
Environments
Within a tenant, Welkin supports multiple environments (e.g., live, sandbox). Environments share the same tenant configuration but maintain separate patient data. This lets you test integrations without affecting production records.
The environment is specified as a query parameter or in the request path, depending on the endpoint.
Patients
A Patient is the central entity in Welkin. All clinical data — encounters, assessments, communications, documents, programs — is associated with a patient record. Patients are identified by a system-generated UUID (patientId).
When creating a patient via API, you can also supply an externalId to map the Welkin record to an identifier from your own system (e.g., your EHR's patient ID).
Custom Data Types (CDTs)
Welkin's data model is schema-first and fully configurable. Rather than a fixed set of fields, your organization defines Custom Data Types (CDTs) in the Designer portal. Each CDT is a named collection of fields (CDTFs — Custom Data Type Fields) that store typed values: text, integer, float, boolean, date, list, and more.
CDTs map to API resources under:
The CDT name in the API matches the machine-readable name defined in Designer (lowercase, underscores). Always confirm CDT names with your Designer configuration before building integrations.
Encounters
An Encounter represents a clinical visit, call, or interaction between a care team member and a patient. Encounters have:
A type (defined in Designer as an Encounter Type)
A status (
OPEN,COMPLETED,DELETED)Associated assessments (forms completed during the encounter)
Notes (free-text clinical documentation)
Encounter records can be created, updated, and finalized via API. Once an encounter is moved to COMPLETED, its assessments are locked.
Assessments and Forms
An Assessment is a structured form filled out during or outside of an encounter. Assessments are based on Form Templates configured in Designer. Assessment responses are stored as CDT values linked to the patient and encounter.
To retrieve assessment responses via API, query the CDT records associated with the patient — the Assessment template determines which CDTs are populated.
Programs and Phases
Welkin organizes care delivery using Programs and Phases:
A Program represents a care pathway (e.g., "Diabetes Management", "Onboarding")
A Phase is a stage within a program (e.g., "Intake", "Active Care", "Discharge")
Patients are enrolled in a program and progress through phases over time. Program and phase enrollment affects which encounters, assessments, and automations are available to a patient.
API endpoints for program enrollment:
Roles and Security Policies
Access to patient data is governed by Roles and Security Policies configured in Designer and assigned in Admin:
Roles define what a care team member can do (e.g., "Nurse", "Care Coordinator", "Admin")
Security Policies apply CRUD permissions at the field level for each role
API clients are also assigned roles, which means your integration will only be able to read or write fields that your API client's role permits. If you receive unexpected 403 responses, check the role and security policy assigned to your API client in Admin.
Authentication
Welkin uses OAuth 2.0 Client Credentials for API authentication. You obtain an access token using your API client's clientId and clientSecret, provisioned in the Admin portal:
The response includes a Bearer token to include in subsequent API request headers:
Tokens expire — implement token refresh logic in your integration. See Welkin API Postman Collection for working examples.
Webhooks
Welkin can push real-time event notifications to your system via Webhooks. Instead of polling the API, configure a webhook endpoint in Designer to receive events such as:
Patient created or updated
Encounter completed
Assessment submitted
Program phase changed
Webhook payloads are signed with an HMAC secret so you can verify authenticity. See Webhooks in the Designer guide for setup instructions.
Pagination and Rate Limits
All list endpoints return paginated results. Use the page and size query parameters to navigate pages. The response includes totalElements and totalPages metadata.
The API enforces rate limits per API client. A 429 Too Many Requests response means you've exceeded the limit. Implement exponential backoff with jitter in your integration. See Data Retrieval for detailed pagination and filtering guidance.
Related Topics
Welkin API Postman Collection — ready-to-use API examples
Data Retrieval — pagination, filtering, and querying
API Exports — bulk data export
Provisioning API Client — setting up API credentials in Admin
Webhooks — real-time event notifications
Custom Data Types — CDT configuration in Designer
Last updated
Was this helpful?