# 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: ``` GET /v1/{tenant}/patients/{patientId}/cdts/{cdtName} POST /v1/{tenant}/patients/{patientId}/cdts/{cdtName} ``` 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: ``` GET /v1/{tenant}/patients/{patientId}/programs POST /v1/{tenant}/patients/{patientId}/programs/{programName}/phases/{phaseName} ``` ## 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: ``` POST https://api.welkinhealth.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &client_id={clientId} &client_secret={clientSecret} ``` The response includes a `Bearer` token to include in subsequent API request headers: ``` Authorization: Bearer {access_token} ``` Tokens expire — implement token refresh logic in your integration. See [Welkin API Postman Collection](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/welkin-api-postman-collection.md) 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](https://welkin-health-1.gitbook.io/welkin-health-docs/designer/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](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/data-retrieval.md) for detailed pagination and filtering guidance. *** ## Related Topics * [Welkin API Postman Collection](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/welkin-api-postman-collection.md) — ready-to-use API examples * [Data Retrieval](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/data-retrieval.md) — pagination, filtering, and querying * [API Exports](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/api-exports.md) — bulk data export * [Provisioning API Client](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/admin/provisioning-api-client.md) — setting up API credentials in Admin * [Webhooks](https://welkin-health-1.gitbook.io/welkin-health-docs/designer/webhooks) — real-time event notifications * [Custom Data Types](https://welkin-health-1.gitbook.io/welkin-health-docs/designer/custom-data-types) — CDT configuration in Designer --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.welkinhealth.com/developer-and-integration-guide/getting-started/core-concepts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.