Overview

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

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. See Authentication for how to exchange your client key/secret for a Bearer token.

Key Concepts

• 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

Base URL & Environments

Every request is scoped to your tenantName (organization) and instanceName (environment: live, sandbox, or a named staging instance). The production host is https://api.live.welkincloud.io; sandbox and staging instances use the equivalent host for that environment.

Rate Limits

Standard rate limits start at 10 requests per second and 100,000 calls per day, per API client. If your integration needs higher throughput, contact your Customer Success Representative to discuss flexibility with these limits. See Rate Limits for how the API signals that you've hit a limit and how to handle it.

Resource Overview

• Patient — create, search, and manage patient records
• Custom Data Types (CDT) Formation — read Custom Data Type schema definitions
• CDT Record — CRUD operations on CDT record instances
• Profile Data Types (PDT) Formation — read Profile Data Type schema definitions
• PDT Record — CRUD operations on patient profile data
• Contact — manage patient contacts
• Encounters — create and manage clinical encounters
• User — manage care team users and territories
• Assessment Formation — read assessment schema definitions
• Assessment Record — create and manage assessment responses
• Calls — access voice call records and recordings
• Sms — access SMS message records
• Email — access email records and drafts
• Chat — send and retrieve in-app chat messages
• Care Plan — read patient care plans and goals
• Calendar API — manage calendar events and schedules
• Program — read program definitions
• Task Management — create and manage care team tasks
• Patient Program — enroll patients and manage program phases
• Dictionaries — access dictionary formation and records
• Audit — retrieve audit logs of system and user activity
• Export — bulk export data across all patients (CDT records, assessments, calls, and more)
• Document Types — read document type definitions
• Documents — upload and manage patient documents
• Unrecognized Calls — manage inbound calls from unrecognized numbers
• Unrecognized SMS — manage inbound SMS from unrecognized numbers
• Unrecognized Emails — manage inbound email from unrecognized senders
• Payments & Subscriptions — manage patient payments and subscription plans
• Invoices — manage patient invoices
• Communication API — send outbound communications across channels
• Messaging Templates — manage reusable message templates
• Fax — send and receive fax documents