# Developer & Integration Guide

Welcome to the **Welkin Health API documentation**. This guide covers everything you need to build integrations with the Welkin platform — from authentication and patient management to assessments, communications, and data exports.

## Base URL

All API requests use the following base URL pattern:

```
https://api.welkinhealth.com/{tenantName}/{instanceName}/
```

| Variable       | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `tenantName`   | Your organization's unique tenant identifier                           |
| `instanceName` | The target environment: `live`, `sandbox`, or a named staging instance |

## Authentication

All API requests require a **Bearer token**. Tokens are obtained by calling the [Authentication endpoint](/developer-and-integration-guide/getting-started/authentication.md) using your API client credentials (key + secret). Tokens expire after **1 hour** and should be cached to avoid rate limiting.

```http
Authorization: Bearer <access_token>
```

> **Rate limit:** Requesting a token more than 100 times per 5 minutes will result in a 5-minute block.

## API Clients

API access is granted via an **API Client** — an auto-generated key/secret pair created in the Welkin Admin panel. Each client can be scoped with specific Security Policies to limit access to only the resources your integration needs.

## Key Concepts

| Concept             | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **Tenant**          | Your organization's dedicated space in Welkin (also called Organization)                     |
| **Instance**        | An isolated database within a Tenant — typically `live`, `sandbox`, or a staging environment |
| **API Client**      | A key/secret pair used to authenticate API requests                                          |
| **Security Policy** | Rules that define what resources an API client can read or write                             |
| **Designer**        | Welkin's codeless editor for configuring care programs, forms, and workflows                 |

## Resource Overview

| Category                                                                                                  | Description                                   |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| [Authentication](/developer-and-integration-guide/getting-started/authentication.md)                      | Obtain Bearer tokens                          |
| [Patients](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/api-reference/patients.md) | Create, search, and manage patient records    |
| [CDT Formation](/developer-and-integration-guide/api-reference/cdt-formation.md)                          | Read Custom Data Type schema definitions      |
| [Custom Data Types (CDT)](/developer-and-integration-guide/api-reference/custom-data-types.md)            | CRUD operations on CDT record instances       |
| [Profile Formation](/developer-and-integration-guide/api-reference/profile-formation.md)                  | Read Profile Data Type schema definitions     |
| [Profile Records](/developer-and-integration-guide/api-reference/profile-records.md)                      | CRUD operations on patient profile data       |
| [Contacts](/developer-and-integration-guide/api-reference/contacts.md)                                    | Manage patient contacts                       |
| [Encounters](/developer-and-integration-guide/api-reference/encounters.md)                                | Create and manage clinical encounters         |
| [Users](/developer-and-integration-guide/api-reference/users.md)                                          | Manage care team users and territories        |
| [Assessment Formation](/developer-and-integration-guide/api-reference/assessment-formation.md)            | Read assessment schema definitions            |
| [Assessment Records](/developer-and-integration-guide/api-reference/assessment-records.md)                | Create and manage assessment responses        |
| [Calls](/developer-and-integration-guide/api-reference/calls.md)                                          | Access voice call records and recordings      |
| [SMS](/developer-and-integration-guide/api-reference/sms.md)                                              | Access SMS message records                    |
| [Email](/developer-and-integration-guide/api-reference/email.md)                                          | Access email records and drafts               |
| [Chat / History](/developer-and-integration-guide/api-reference/chat-history.md)                          | Send and retrieve in-app chat messages        |
| [Care Plan](/developer-and-integration-guide/api-reference/care-plan.md)                                  | Read patient care plans and goals             |
| [Calendar](/developer-and-integration-guide/api-reference/calendar.md)                                    | Manage calendar events and schedules          |
| [Programs](/developer-and-integration-guide/api-reference/programs.md)                                    | Read program definitions                      |
| [Task Management](/developer-and-integration-guide/api-reference/task-management.md)                      | Create and manage care team tasks             |
| [Patient Programs](/developer-and-integration-guide/api-reference/patient-programs.md)                    | Enroll patients and manage program phases     |
| [Dictionaries](/developer-and-integration-guide/api-reference/dictionaries.md)                            | Access dictionary formation and records       |
| [Audit](/developer-and-integration-guide/api-reference/audit.md)                                          | Retrieve data audit and webhook audit logs    |
| [Export](/developer-and-integration-guide/api-reference/export.md)                                        | Bulk export records across all resource types |
| [Document Types](/developer-and-integration-guide/api-reference/document-types.md)                        | Read document type schema definitions         |
| [Documents](/developer-and-integration-guide/api-reference/documents.md)                                  | Manage document summary and document records  |
| [Unrecognized Calls](/developer-and-integration-guide/api-reference/unrecognized-calls.md)                | Access inbound calls with no matched patient  |
| [Unrecognized SMS](/developer-and-integration-guide/api-reference/unrecognized-sms.md)                    | Access inbound SMS with no matched patient    |
| [Unrecognized Emails](/developer-and-integration-guide/api-reference/unrecognized-emails.md)              | Access inbound emails with no matched patient |
| [Payments & Subscriptions](/developer-and-integration-guide/api-reference/payments.md)                    | Manage payment methods and subscriptions      |
| [Invoices](/developer-and-integration-guide/api-reference/invoices.md)                                    | Retrieve invoice records                      |
| [Communication API](/developer-and-integration-guide/api-reference/communication-api.md)                  | Create communication IDs for SMS delivery     |
| [Messaging Templates](/developer-and-integration-guide/api-reference/messaging-templates.md)              | Resolve dynamic message templates             |

## Postman Collection

All endpoints are available in the official [**Welkin Public Postman Collection**](https://www.postman.com/welikan/public-welkinhealth-api/collection/4uz6kkh/welkin).

***

For questions or integration support, contact the Welkin Health platform team.


---

# 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/readme.md?ask=<question>
```

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.