Overview

Welkin’s goal is to empower you, our customers, to deliver patient-centered care. Our API exists in support of this goal. Whether it’s data kept within our platform, or your pre-existing systems, we think you should have complete, real-time access and agency over your own data.

Using Welkin's APIs will allow you to keep your systems in sync with Welkin.

By design, our API notifies your subscribed systems of any updates to your resources within Welkin. For example, when a patient's phone number is changed in Welkin, that information is immediately sent to your systems, keeping them up to date with the latest values stored in our platform.

Welkin's API also transfer the data created and updated in your 3rd party systems into our platform, keeping your information across systems aligned.

This documentation outlines the data types available via Welkin’s APIs and the usage of these APIs. APIs exist for all of the core data types managed within Welkin.

Base URL: https://api.welkinhealth.com

API updates

Welkin's API is in active development. We will be making backwards compatible changes over the coming months with little or no advanced notice. You should expect Welkin to add additional optional fields to resource schemas and new resource types to the API. Your integration should be built with this understanding and should not break with the addition of new fields or resource types. Use of strict schema validation is not recommended. Breaking changes will be communicated in advance of rollout and we will work with you to make the transition.

Authentication

JWT_BEARER_URI = 'urn:ietf:params:oauth:grant-type:jwt-bearer'

def get_token(client_id, client_secret, scope, endpoint, audience):
  claim = {
    'iss': client_id,
    'aud': audience,
    'exp': arrow.utcnow().replace(seconds=3600).timestamp,
    'scope': scope,
  }
  assertion = jwt.encode(claim, client_secret, algorithm='HS256')
  params = {
    'assertion': assertion,
    'grant_type': JWT_BEARER_URI
  }
  resp = requests.post(endpoint, data=params)
  token = resp.json()['access_token']
  return token

token = get_token('<client_id>',
                  '<client_secret>',
                  'all',
                  'https://api.welkinhealth.com/v1/token',
                  'https://api.welkinhealth.com/v1/token')

headers = {"Authorization": "Bearer <token>"}

resp = requests.post('https://api.welkinhealth.com/v1/patients', headers=headers).json()

Welkin's APIs are secured using a 2-legged OAuth JWT-Bearer authorization flow. This ensures that data stored within Welkin remains secure and is not accessible by unauthorized parties.

For testing purposes, Welkin provides a long-lived access token but the use of 2-legged OAuth is still required for production.

Once you obtain an access token, the token can be passed as an Authorization header along with the keyword Bearer.

More information on the JWT protocol can be found at jwt.io.

A simple guide to understanding JWT can be found in this Medium article.

Update Notifications

Welkin's APIs work using a “ping and pull” model. This means our APIs notify subscribers via Webhook any time there’s an update to your data within our platform. Your subscribers can then decide if you want to pull the updated resources into your system, from Welkin. This ensures your systems are kept up to date with the latest data changes in our platform, without needing to continuously poll our APIs.

The webhook notification includes which resources have changed, the time range of the changes, and a url to use in a GET request to fetch the changes (see Find endpoints for each resource).

Webhook notifications are delayed up to 60 seconds, from the time the resource is changed in Welkin.

An example of Welkin’s data sync could look like the following:

Alex, a worker, logs into Welkin and updates the phone number in the patient's (Allison) profile.
Welkin sends a notification to the customer’s 3rd party system, letting them know that the patient object for Allison has been changed.
In response, the 3rd party system requests the full patient object for Allison, which contains the new phone number.
The system processes the updated patient object and saves it.
Both Welkin and the customer’s integrated system are now in sync, both reflecting Allison’s updated phone number.

Webhook body

Each notification contains all the updates for all the resource types since the last successful notification.

[ { "resource": "patients",
    "from": "2018-05-14T23:34:05.647496",
    "to": "2018-05-15T23:34:05.647496",
    "href": "https://api.welkinhealth.com/v1/patients?page[to]=2018-05-15T23:34:05.647496&page[from]=2018-05-14T23:34:05.647496"}]

Model notification webhook request body

field	type	description
_	`list`	List of data_update_notification objects

Model data_update_notification

field	type	description
resource	`string`	Resource endpoint path name
from	`isodatetime`	Datetime of first update
to	`isodatetime`	Datetime of latest update
href	`string`	Link to GET all updates for this notification

Webhook security

Welkin's APIs expect that the webhook destination is secured using JWT Bearer Authorization in the same manor that our core API is secured. This ensures that patient data remains secure and protected at all times.

Find endpoints

curl -XGET /v1/patients?page[from]=2018-06-15T10:30:01&page[to]=2018-09-30T10:29:59&page[size]=10

You can pull large batches of data from Welkin at anytime using the Find endpoint for any API resource. These endpoints support filtering by time ranges. If your system misses notifications or needs data from a specific time range you should use the Find endpoints to pull data for the missing time range.

The example here pulls patients created or updated during the time range June 15th 2018 to September 30th 2018.

API Reference

App Messages

App Messages can be viewed or created from the conversation view of the Patient Profile. App Messages are text based communications that are sent to patients via a web or mobile app and do not include emails or sms messages.

Model

{
  "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00", 
  "updated_at": "2018-09-12T01:27:32.045196+00:00", 
  "created_at": "2018-09-12T01:27:32.045336+00:00"
}

param	description
id `guid`	The primary identifier
patient_id `guid`	ID of the patient who sent or received this message.
worker_id `guid`	ID of the worker who sent this message. Note: inbound messages do not have a `worker_id`
conversation_id `guid`	ID of the conversation that this messages is contained in
direction `enum`	Direction of the messsage from the perspective of the worker (`inbound` or `outbound`)
contents `string`	Text of the message
automatically_sent `boolean`	Denotes whether the message was created and sent from Welkin by a worker, or via automated process
sent_at `isodatetime`	Date and time when the message was sent
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single app message.

Invocation

curl -XGET /v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26

GET /v1/app_messages/:id

{
  "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00", 
  "updated_at": "2018-09-12T01:27:32.045196+00:00", 
  "created_at": "2018-09-12T01:27:32.045336+00:00"
}

Params

param	description
id `guid`	The primary identifier

Update

Update the time at which the message was sent. This is to be used when an outside system sends the app messages on behalf of Welkin to the patient.

Invocation

curl -XPUT /v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26 -d '{
  "sent_at": "2018-09-12T01:27:32.045046+00:00"
}'

PUT /v1/app_messages/:id -d { }

{
  "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00", 
  "updated_at": "2018-09-12T01:27:32.045196+00:00", 
  "created_at": "2018-09-12T01:27:32.045336+00:00"
}

Params

param	description
id `guid`	The primary identifier
sent_at `optional isodatetime`	Date and time when the message was sent

Create

New messages can be created in a Patient Profile. Messages created in Welkin are recorded in the conversation view.

Invocation

curl -XPOST /v1/app_messages -d '{
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "sent_at": "2018-09-12T01:27:32.045046+00:00"
}'

POST /v1/app_messages -d { }

{
  "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00", 
  "updated_at": "2018-09-12T01:27:32.045196+00:00", 
  "created_at": "2018-09-12T01:27:32.045336+00:00"
}

Params

param	description
patient_id `guid`	ID of the patient who sent or received this message.
worker_id `guid`	ID of the worker who sent this message. Note: inbound messages do not have a `worker_id`
conversation_id `guid`	ID of the conversation that this messages is contained in
direction `enum`	Direction of the messsage from the perspective of the worker (`inbound` or `outbound`)
contents `string`	Text of the message
sent_at `optional isodatetime`	Date and time when the message was sent

Find

Finds app messages, using param filters.

Invocation

curl -XGET /v1/app_messages

GET /v1/app_messages

[
  {
    "data": [
      {
        "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
        "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
        "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
        "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
        "direction": "inbound", 
        "contents": "Hi Developer, Welcome to Welkin Health.", 
        "automatically_sent": false, 
        "sent_at": "2018-09-12T01:27:32.045046+00:00", 
        "updated_at": "2018-09-12T01:27:32.045196+00:00", 
        "created_at": "2018-09-12T01:27:32.045336+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.682273+00:00", 
        "page[to]": "2019-01-23T01:26:06.682293+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
patient_id `optional guid`	ID of the patient who sent or received this message.
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Assessment Responses

Assessments can be completed in external systems, and loaded into Welkin for display in the Welkin Portal.

The data format of assessment responses created via this API must match existing assessment templates which have been created in Workshop.

Similarly, Assessments completed in Welkin can be retrieved via this API.

Model

{
  "id": "20c04e56-69f0-4d13-b5c1-a1763abd1218", 
  "spec_name": "formation_specs_d3da7fc6-77e3-4982-800a-bcaa6983a611", 
  "spec_version": "a83acefd-b97c-4d05-99a8-003d443409dc", 
  "patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6", 
  "model": {
    "insurance_provider": "Acme Insurance", 
    "plan_type": "SILVER", 
    "active": true, 
    "years_active": 2, 
    "last_hcp_visit": "2018-07-14", 
    "pain_scale": 0.4, 
    "completed_at": "2018-08-12T10:20:15"
  }, 
  "updated_at": "2018-09-12T01:27:32.024836+00:00", 
  "created_at": "2018-09-12T01:27:32.025031+00:00"
}

param	description
id `guid`	The primary identifier
spec_id `string`	(Deprecated) ID of the assessment which this response corresponds to. This is only used for assessments created in code by Welkin engineers.
spec_name `string`	The ref_name for the assessment as it appears in Workshop.
spec_version `string`	Optionally, the version string of assessment spec. If not specified, the most recent spec version authored in Workshop will be used.
patient_id `guid`	ID of the patient
model `json`	Response data for assessment fields. The schema for this JSON object can be found in Workshop.
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single assessment response.

Invocation

curl -XGET /v1/assessment_responses/20c04e56-69f0-4d13-b5c1-a1763abd1218

GET /v1/assessment_responses/:id

{
  "id": "20c04e56-69f0-4d13-b5c1-a1763abd1218", 
  "spec_name": "formation_specs_d3da7fc6-77e3-4982-800a-bcaa6983a611", 
  "spec_version": "a83acefd-b97c-4d05-99a8-003d443409dc", 
  "patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6", 
  "model": {
    "insurance_provider": "Acme Insurance", 
    "plan_type": "SILVER", 
    "active": true, 
    "years_active": 2, 
    "last_hcp_visit": "2018-07-14", 
    "pain_scale": 0.4, 
    "completed_at": "2018-08-12T10:20:15"
  }, 
  "updated_at": "2018-09-12T01:27:32.024836+00:00", 
  "created_at": "2018-09-12T01:27:32.025031+00:00"
}

Params

param	description
id `guid`	The primary identifier

Create

Creates a new assessment response.

Invocation

curl -XPOST /v1/assessment_responses -d '{
  "spec_id": "some_string", 
  "spec_name": "formation_specs_d3da7fc6-77e3-4982-800a-bcaa6983a611", 
  "spec_version": "a83acefd-b97c-4d05-99a8-003d443409dc", 
  "patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6", 
  "model": {
    "insurance_provider": "Acme Insurance", 
    "plan_type": "SILVER", 
    "active": true, 
    "years_active": 2, 
    "last_hcp_visit": "2018-07-14", 
    "pain_scale": 0.4, 
    "completed_at": "2018-08-12T10:20:15"
  }, 
  "title": "some_string"
}'

POST /v1/assessment_responses -d { }

{
  "id": "20c04e56-69f0-4d13-b5c1-a1763abd1218", 
  "spec_name": "formation_specs_d3da7fc6-77e3-4982-800a-bcaa6983a611", 
  "spec_version": "a83acefd-b97c-4d05-99a8-003d443409dc", 
  "patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6", 
  "model": {
    "insurance_provider": "Acme Insurance", 
    "plan_type": "SILVER", 
    "active": true, 
    "years_active": 2, 
    "last_hcp_visit": "2018-07-14", 
    "pain_scale": 0.4, 
    "completed_at": "2018-08-12T10:20:15"
  }, 
  "updated_at": "2018-09-12T01:27:32.024836+00:00", 
  "created_at": "2018-09-12T01:27:32.025031+00:00"
}

Params

param	description
spec_id `optional string`	(Deprecated) ID of the assessment which this response corresponds to. This is only used for assessments created in code by Welkin engineers.
spec_name `optional string`	The ref_name for the assessment as it appears in Workshop.
spec_version `optional string`	Optionally, the version string of assessment spec. If not specified, the most recent spec version authored in Workshop will be used.
patient_id `guid`	ID of the patient
model `anything`	Response data for assessment fields. The schema for this JSON object can be found in Workshop.
title `optional string`	The title of the assessment response to be displayed in the timeline.

Find

Finds assessment responses, using param filters.

Invocation

curl -XGET /v1/assessment_responses

GET /v1/assessment_responses

[
  {
    "data": [
      {
        "id": "20c04e56-69f0-4d13-b5c1-a1763abd1218", 
        "spec_name": "formation_specs_d3da7fc6-77e3-4982-800a-bcaa6983a611", 
        "spec_version": "a83acefd-b97c-4d05-99a8-003d443409dc", 
        "patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6", 
        "model": {
          "insurance_provider": "Acme Insurance", 
          "plan_type": "SILVER", 
          "active": true, 
          "years_active": 2, 
          "last_hcp_visit": "2018-07-14", 
          "pain_scale": 0.4, 
          "completed_at": "2018-08-12T10:20:15"
        }, 
        "updated_at": "2018-09-12T01:27:32.024836+00:00", 
        "created_at": "2018-09-12T01:27:32.025031+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.690192+00:00", 
        "page[to]": "2019-01-23T01:26:06.690205+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Calendar Events

Calendar events are appointments on worker calenders. They're in reference to a patient. A calendar event can be scheduled for a date and time or simply for a date.

If is_all_day is set to true then you must set day. If is_all_day is set to false then you must use start_time and end_time.

Model

{
  "id": "f2baaf15-94d2-415d-b3e6-7409b643d297", 
  "calendar_id": "598de18b-b203-4947-be34-6871188cd81d", 
  "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
  "is_all_day": false, 
  "start_time": "2018-09-10T18:56:19.357228+00:00", 
  "end_time": "2018-09-10T18:56:19.357540+00:00", 
  "outcome": "completed", 
  "modality": "phone", 
  "appointment_type": "intake_call", 
  "updated_at": "2018-09-10T18:56:19.359240+00:00", 
  "created_at": "2018-09-10T18:56:19.359873+00:00"
}

param	description
id `guid`	The primary identifier
calendar_id `guid`	ID of the calendar on which this event resides
patient_id `guid`	ID of the patient
user_id `guid`	(Deprecated) ID of the patient
is_all_day `boolean`	`true` if not scheduled for a specific time of day. `false` otherwise
start_time `optional isodatetime`	Scheduled start time of the calendar event if scheduled for a specific time of day
end_time `optional isodatetime`	Scheduled end time of the calendar event if scheduled for a specific time of day
day `date`	Date of the calendar event if not scheduled for a specific time of day
outcome `enum`	The result of the event if it is no longer upcoming (`completed`, `cancelled`, `no-show`)
modality `enum`	Mode via which the event will take place (`call`, `visit`, `video`)
appointment_type `string`	Appointment prompt to be used for this event (see note for details)
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single calendar event.

Invocation

curl -XGET /v1/calendar_events/f2baaf15-94d2-415d-b3e6-7409b643d297

GET /v1/calendar_events/:id

{
  "id": "f2baaf15-94d2-415d-b3e6-7409b643d297", 
  "calendar_id": "598de18b-b203-4947-be34-6871188cd81d", 
  "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
  "is_all_day": false, 
  "start_time": "2018-09-10T18:56:19.357228+00:00", 
  "end_time": "2018-09-10T18:56:19.357540+00:00", 
  "outcome": "completed", 
  "modality": "phone", 
  "appointment_type": "intake_call", 
  "updated_at": "2018-09-10T18:56:19.359240+00:00", 
  "created_at": "2018-09-10T18:56:19.359873+00:00"
}

Params

param	description
id `guid`	The primary identifier

Update

Updates an existing calendar event.

Invocation

curl -XPUT /v1/calendar_events/f2baaf15-94d2-415d-b3e6-7409b643d297 -d '{
  "start_time": "2018-09-10T18:56:19.357228+00:00", 
  "end_time": "2018-09-10T18:56:19.357540+00:00", 
  "outcome": "completed"
}'

PUT /v1/calendar_events/:id -d { }

{
  "id": "f2baaf15-94d2-415d-b3e6-7409b643d297", 
  "calendar_id": "598de18b-b203-4947-be34-6871188cd81d", 
  "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
  "is_all_day": false, 
  "start_time": "2018-09-10T18:56:19.357228+00:00", 
  "end_time": "2018-09-10T18:56:19.357540+00:00", 
  "outcome": "completed", 
  "modality": "phone", 
  "appointment_type": "intake_call", 
  "updated_at": "2018-09-10T18:56:19.359240+00:00", 
  "created_at": "2018-09-10T18:56:19.359873+00:00"
}

Params

param	description
id `guid`	The primary identifier
start_time `optional isodatetime`	Scheduled start time of the calendar event if scheduled for a specific time of day
end_time `optional isodatetime`	Scheduled end time of the calendar event if scheduled for a specific time of day
day `optional date`	Date of the calendar event if not scheduled for a specific time of day
outcome `optional enum`	The result of the event if it is no longer upcoming (`completed`, `cancelled`, `no-show`)

Create

Creates a new calendar event.

Invocation

curl -XPOST /v1/calendar_events -d '{
  "calendar_id": "598de18b-b203-4947-be34-6871188cd81d", 
  "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
  "user_id": "84b423f9-c649-4215-b479-7ba5aefa7c71", 
  "start_time": "2018-09-10T18:56:19.357228+00:00", 
  "end_time": "2018-09-10T18:56:19.357540+00:00", 
  "modality": "phone", 
  "appointment_type": "intake_call"
}'

POST /v1/calendar_events -d { }

{
  "id": "f2baaf15-94d2-415d-b3e6-7409b643d297", 
  "calendar_id": "598de18b-b203-4947-be34-6871188cd81d", 
  "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
  "is_all_day": false, 
  "start_time": "2018-09-10T18:56:19.357228+00:00", 
  "end_time": "2018-09-10T18:56:19.357540+00:00", 
  "outcome": "completed", 
  "modality": "phone", 
  "appointment_type": "intake_call", 
  "updated_at": "2018-09-10T18:56:19.359240+00:00", 
  "created_at": "2018-09-10T18:56:19.359873+00:00"
}

Params

param	description
calendar_id `guid`	ID of the calendar on which this event resides
patient_id `optional guid`	ID of the patient
user_id `optional guid`	(Deprecated) ID of the patient
start_time `optional isodatetime`	Scheduled start time of the calendar event if scheduled for a specific time of day
end_time `optional isodatetime`	Scheduled end time of the calendar event if scheduled for a specific time of day
day `optional date`	Date of the calendar event if not scheduled for a specific time of day
modality `enum`	Mode via which the event will take place (`call`, `visit`, `video`)
appointment_type `string`	Appointment prompt to be used for this event (see note for details)

Find

Finds calendar events, using param filters.

Invocation

curl -XGET /v1/calendar_events

GET /v1/calendar_events

[
  {
    "data": [
      {
        "id": "f2baaf15-94d2-415d-b3e6-7409b643d297", 
        "calendar_id": "598de18b-b203-4947-be34-6871188cd81d", 
        "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
        "is_all_day": false, 
        "start_time": "2018-09-10T18:56:19.357228+00:00", 
        "end_time": "2018-09-10T18:56:19.357540+00:00", 
        "outcome": "completed", 
        "modality": "phone", 
        "appointment_type": "intake_call", 
        "updated_at": "2018-09-10T18:56:19.359240+00:00", 
        "created_at": "2018-09-10T18:56:19.359873+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.701940+00:00", 
        "page[to]": "2019-01-23T01:26:06.701957+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Calendars

Calendars link Calendar Events to Workers.

Model

{
  "id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
  "worker_id": "f9850af8-2ab0-4542-b281-cf4d5442bbd5", 
  "updated_at": "2018-09-12T01:27:32.028059+00:00", 
  "created_at": "2018-09-12T01:27:32.028187+00:00"
}

param	description
id `guid`	The primary identifier
worker_id `guid`	The ID of the worker who's calendar this is
updated_at `isodatetime`	Datetime the resource was created (excluding updates to events on this calendar)
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single calendar.

Invocation

curl -XGET /v1/calendars/0d5de756-cdda-4cc0-9cca-bcdc36b1a92f

GET /v1/calendars/:id

{
  "id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
  "worker_id": "f9850af8-2ab0-4542-b281-cf4d5442bbd5", 
  "updated_at": "2018-09-12T01:27:32.028059+00:00", 
  "created_at": "2018-09-12T01:27:32.028187+00:00"
}

Params

param	description
id `guid`	The primary identifier

Find

Finds calendars, using param filters.

Invocation

curl -XGET /v1/calendars

GET /v1/calendars

[
  {
    "data": [
      {
        "id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
        "worker_id": "f9850af8-2ab0-4542-b281-cf4d5442bbd5", 
        "updated_at": "2018-09-12T01:27:32.028059+00:00", 
        "created_at": "2018-09-12T01:27:32.028187+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.706028+00:00", 
        "page[to]": "2019-01-23T01:26:06.706042+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Care Flows

Care Flows lay out a set of tasks, or multiple sets of tasks, to help the patient achieve 1 or more Goals.

Model care_flow

field	type	description
title	`string`	Title of the overall Care Flow
description	`string`	Description of the overall Care Flow
goals	`list`	List of goal objects

Model Goal

field	type	description
title	`string`	Title of the Care Flow goal
tasks	`list`	List of goal intervention objects

Model Intervention

field	type	description	optional
description	`string`	Title of the Care Flow intervention	required
reminder_date	`isodatetime`	Due date for the intervention	optional
completed_at	`isodatetime`	Date the intervention was marked completed	optional
completed_by_worker_id	`guid`	ID of the worker who completed this intervention	optional
worker_id	`guid`	ID of the worker who this intervention is assigned to	optional

Get

Retrieves a single care flow.

Invocation

curl -XGET /v1/care_flows/c68a80d4-95ea-4f61-bf90-615d70bea591

GET /v1/care_flows/:id

{
  "id": "c68a80d4-95ea-4f61-bf90-615d70bea591", 
  "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
  "care_flow": {
    "title": "patient needs at least 30min exercise per day", 
    "description": "increase daily exercise", 
    "goals": [
      {
        "title": "Make a plan", 
        "tasks": [
          {
            "description": "Help the patient decide what type of exercise they can commit to doing.", 
            "due_date": "2018-08-07T00:00:00+00:00", 
            "worker_id": null, 
            "completed_by_worker_id": null, 
            "completed_at": null
          }, 
          {
            "description": "Make sure there is a written record of the patient's new exercise plan", 
            "due_date": "2018-08-10T00:00:00+00:00", 
            "worker_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
            "completed_by_worker_id": null, 
            "completed_at": null
          }
        ]
      }
    ]
  }, 
  "updated_at": "2018-09-12T01:27:32.029691+00:00", 
  "created_at": "2018-09-12T01:27:32.029817+00:00"
}

Params

param	description
id `guid`	The primary identifier

Find

Finds care flows, using param filters.

Invocation

curl -XGET /v1/care_flows

GET /v1/care_flows

[
  {
    "data": [
      {
        "id": "c68a80d4-95ea-4f61-bf90-615d70bea591", 
        "patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180", 
        "care_flow": {
          "title": "patient needs at least 30min exercise per day", 
          "description": "increase daily exercise", 
          "goals": [
            {
              "title": "Make a plan", 
              "tasks": [
                {
                  "description": "Help the patient decide what type of exercise they can commit to doing.", 
                  "due_date": "2018-08-07T00:00:00+00:00", 
                  "worker_id": null, 
                  "completed_by_worker_id": null, 
                  "completed_at": null
                }, 
                {
                  "description": "Make sure there is a written record of the patient's new exercise plan", 
                  "due_date": "2018-08-10T00:00:00+00:00", 
                  "worker_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
                  "completed_by_worker_id": null, 
                  "completed_at": null
                }
              ]
            }
          ]
        }, 
        "updated_at": "2018-09-12T01:27:32.029691+00:00", 
        "created_at": "2018-09-12T01:27:32.029817+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.709294+00:00", 
        "page[to]": "2019-01-23T01:26:06.709304+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Conversations

Conversations track the text-based conversations between workers and patients.

Text-based communication methods supported by Welkin are: SMS, email, and in-app messaging.

Model

{
  "id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca", 
  "patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88", 
  "conversation_type": "app", 
  "title": "App", 
  "phone_number_id": null, 
  "updated_at": "2018-09-12T01:27:32.031245+00:00", 
  "created_at": "2018-09-12T01:27:32.031362+00:00"
}

param	description
id `guid`	The primary identifier
id `guid`	The primary identifier
patient_id `guid`	ID of the patient participant in this conversation. Only one patient can participate in any single conversation.
conversation_type `enum`	`sms`, `email`, `app` (In app messages to non-Welkin apps), `welkin_app` (Welkin's 1st party in app messages)
title `string`	The title string to be displayed in the conversation view for 3rd party app conversations
phone_number_id `guid`	The ID of the patient's phone number which will be included in this conversation
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single conversation.

Invocation

curl -XGET /v1/conversations/bfa29e70-e328-4c3b-a3d1-7c2d959735ca

GET /v1/conversations/:id

{
  "id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca", 
  "patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88", 
  "conversation_type": "app", 
  "title": "App", 
  "phone_number_id": null, 
  "updated_at": "2018-09-12T01:27:32.031245+00:00", 
  "created_at": "2018-09-12T01:27:32.031362+00:00"
}

Params

param	description
id `guid`	The primary identifier
id `guid`	The primary identifier

Create

Create a 3rd party app conversation for a patient

Invocation

curl -XPOST /v1/conversations -d '{
  "patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88", 
  "conversation_type": "app", 
  "title": "App"
}'

POST /v1/conversations -d { }

{
  "id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca", 
  "patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88", 
  "conversation_type": "app", 
  "title": "App", 
  "phone_number_id": null, 
  "updated_at": "2018-09-12T01:27:32.031245+00:00", 
  "created_at": "2018-09-12T01:27:32.031362+00:00"
}

Params

param	description
patient_id `guid`	ID of the patient participant in this conversation. Only one patient can participate in any single conversation.
conversation_type `enum`	`sms`, `email`, `app` (In app messages to non-Welkin apps), `welkin_app` (Welkin's 1st party in app messages)
title `optional string`	The title string to be displayed in the conversation view for 3rd party app conversations

Find

Finds conversations, using param filters.

Invocation

curl -XGET /v1/conversations

GET /v1/conversations

[
  {
    "data": [
      {
        "id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca", 
        "patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88", 
        "conversation_type": "app", 
        "title": "App", 
        "phone_number_id": null, 
        "updated_at": "2018-09-12T01:27:32.031245+00:00", 
        "created_at": "2018-09-12T01:27:32.031362+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.714762+00:00", 
        "page[to]": "2019-01-23T01:26:06.714774+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
patient_id `optional guid`	ID of the patient participant in this conversation. Only one patient can participate in any single conversation.
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Custom Data Type Records

Welkin stores the custom data associated with patients in custom data type records. The custom data types must first be defined in Workshop before they can be addressed in the API.

Model

{
  "id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7", 
  "body": {
    "name": "Frank Smith", 
    "suffix": "MD", 
    "practice_name": "Boston Medical Group", 
    "office_id": "e32ac52", 
    "specialty": "internal medicine"
  }, 
  "patient_id": "a162d51e-7791-476a-bf9c-c631e178e3c4", 
  "type_name": "hcp", 
  "updated_at": "2018-09-12T01:27:32.033666+00:00", 
  "created_at": "2018-09-12T01:27:32.033816+00:00"
}

param	description
id `guid`	The primary identifier
body `json`	The content of the custom date type record
patient_id `guid`	The ID of the patient
type_name `string`	ID of the custom data type as defined in Workshop
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single custom data type record.

Invocation

curl -XGET /v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7

GET /v1/custom_data_type_records/:id

{
  "id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7", 
  "body": {
    "name": "Frank Smith", 
    "suffix": "MD", 
    "practice_name": "Boston Medical Group", 
    "office_id": "e32ac52", 
    "specialty": "internal medicine"
  }, 
  "patient_id": "a162d51e-7791-476a-bf9c-c631e178e3c4", 
  "type_name": "hcp", 
  "updated_at": "2018-09-12T01:27:32.033666+00:00", 
  "created_at": "2018-09-12T01:27:32.033816+00:00"
}

Params

param	description
id `guid`	The primary identifier

Update

Updates an existing custom data type record.

Invocation

curl -XPUT /v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7 -d '{
  "body": {
    "name": "Frank Smith", 
    "suffix": "MD", 
    "practice_name": "Boston Medical Group", 
    "office_id": "e32ac52", 
    "specialty": "internal medicine"
  }
}'

PUT /v1/custom_data_type_records/:id -d { }

{
  "id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7", 
  "body": {
    "name": "Frank Smith", 
    "suffix": "MD", 
    "practice_name": "Boston Medical Group", 
    "office_id": "e32ac52", 
    "specialty": "internal medicine"
  }, 
  "patient_id": "a162d51e-7791-476a-bf9c-c631e178e3c4", 
  "type_name": "hcp", 
  "updated_at": "2018-09-12T01:27:32.033666+00:00", 
  "created_at": "2018-09-12T01:27:32.033816+00:00"
}

Params

param	description
id `guid`	The primary identifier
body `anything`	The content of the custom date type record

Create

Creates a new custom data type record.

Invocation

curl -XPOST /v1/custom_data_type_records -d '{
  "body": {
    "name": "Frank Smith", 
    "suffix": "MD", 
    "practice_name": "Boston Medical Group", 
    "office_id": "e32ac52", 
    "specialty": "internal medicine"
  }, 
  "patient_id": "a162d51e-7791-476a-bf9c-c631e178e3c4", 
  "type_name": "hcp"
}'

POST /v1/custom_data_type_records -d { }

{
  "id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7", 
  "body": {
    "name": "Frank Smith", 
    "suffix": "MD", 
    "practice_name": "Boston Medical Group", 
    "office_id": "e32ac52", 
    "specialty": "internal medicine"
  }, 
  "patient_id": "a162d51e-7791-476a-bf9c-c631e178e3c4", 
  "type_name": "hcp", 
  "updated_at": "2018-09-12T01:27:32.033666+00:00", 
  "created_at": "2018-09-12T01:27:32.033816+00:00"
}

Params

param	description
body `anything`	The content of the custom date type record
patient_id `guid`	The ID of the patient
type_name `string`	ID of the custom data type as defined in Workshop

Find

Finds custom data type records, using param filters.

Invocation

curl -XGET /v1/custom_data_type_records

GET /v1/custom_data_type_records

[
  {
    "data": [
      {
        "id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7", 
        "body": {
          "name": "Frank Smith", 
          "suffix": "MD", 
          "practice_name": "Boston Medical Group", 
          "office_id": "e32ac52", 
          "specialty": "internal medicine"
        }, 
        "patient_id": "a162d51e-7791-476a-bf9c-c631e178e3c4", 
        "type_name": "hcp", 
        "updated_at": "2018-09-12T01:27:32.033666+00:00", 
        "created_at": "2018-09-12T01:27:32.033816+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.720759+00:00", 
        "page[to]": "2019-01-23T01:26:06.720772+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
type_name `optional string`	ID of the custom data type as defined in Workshop
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Email Addresses

Manage patient email addresses based on patient consent.

Each patient email address has it's own consents and opt-in status. When setting the consent flags on a email address, make sure that you have a record of how and when consent was received from the patient.

Model

{
  "id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd", 
  "email": "developer@welkinhealth.com", 
  "friendly_name": "developer contact", 
  "patient_id": "14492e35-c4e4-4235-8175-aa874321144e", 
  "verified": false, 
  "opted_in_to_email": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.035940+00:00", 
  "created_at": "2018-09-12T01:27:32.036062+00:00"
}

param	description
id `guid`	The primary identifier
email `email`	Email address for the patient. Note: no validation of format is done on email addresses.
friendly_name `string`	The display name for a patient email address, visible to workers
patient_id `guid`	ID of the patient which this email address is associated with.
user_id `guid`	(Deprecated) ID of the patient which this email address is associated with.
verified `boolean`	`true` only if this email has been verified by the patient clicking on a link in an email to confirm that they received the verification email. This does not guarantee that the email address is owned by the patient. Default `false`
opted_in_to_email `boolean`	`true` only if the patient as consented to receive emails at this email address. If False, then no emails of any kind can be sent to this address. Default `false`
automatic_recipient `boolean`	`true` only if the patient as consented to receive automated emails at this email address. Default `false`
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single email address.

Invocation

curl -XGET /v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd

GET /v1/email_addresses/:id

{
  "id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd", 
  "email": "developer@welkinhealth.com", 
  "friendly_name": "developer contact", 
  "patient_id": "14492e35-c4e4-4235-8175-aa874321144e", 
  "verified": false, 
  "opted_in_to_email": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.035940+00:00", 
  "created_at": "2018-09-12T01:27:32.036062+00:00"
}

Params

param	description
id `guid`	The primary identifier

Update

Updates an existing email address.

Invocation

curl -XPUT /v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd -d '{
  "email": "developer@welkinhealth.com", 
  "friendly_name": "developer contact", 
  "verified": false, 
  "opted_in_to_email": true, 
  "automatic_recipient": false
}'

PUT /v1/email_addresses/:id -d { }

{
  "id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd", 
  "email": "developer@welkinhealth.com", 
  "friendly_name": "developer contact", 
  "patient_id": "14492e35-c4e4-4235-8175-aa874321144e", 
  "verified": false, 
  "opted_in_to_email": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.035940+00:00", 
  "created_at": "2018-09-12T01:27:32.036062+00:00"
}

Params

param	description
id `guid`	The primary identifier
email `optional email`	Email address for the patient. Note: no validation of format is done on email addresses.
friendly_name `optional string`	The display name for a patient email address, visible to workers
verified `optional boolean`	`true` only if this email has been verified by the patient clicking on a link in an email to confirm that they received the verification email. This does not guarantee that the email address is owned by the patient. Default `false`
opted_in_to_email `optional boolean`	`true` only if the patient as consented to receive emails at this email address. If False, then no emails of any kind can be sent to this address. Default `false`
automatic_recipient `optional boolean`	`true` only if the patient as consented to receive automated emails at this email address. Default `false`

Create

Invocation

curl -XPOST /v1/email_addresses -d '{
  "email": "developer@welkinhealth.com", 
  "friendly_name": "developer contact", 
  "patient_id": "14492e35-c4e4-4235-8175-aa874321144e", 
  "user_id": "eb51e051-8963-4dd3-9a61-e25fceb780f9", 
  "verified": false, 
  "opted_in_to_email": true, 
  "automatic_recipient": false
}'

POST /v1/email_addresses -d { }

{
  "id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd", 
  "email": "developer@welkinhealth.com", 
  "friendly_name": "developer contact", 
  "patient_id": "14492e35-c4e4-4235-8175-aa874321144e", 
  "verified": false, 
  "opted_in_to_email": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.035940+00:00", 
  "created_at": "2018-09-12T01:27:32.036062+00:00"
}

Params

param	description
email `email`	Email address for the patient. Note: no validation of format is done on email addresses.
friendly_name `optional string`	The display name for a patient email address, visible to workers
patient_id `guid`	ID of the patient which this email address is associated with.
user_id `optional guid`	(Deprecated) ID of the patient which this email address is associated with.
verified `optional boolean`	`true` only if this email has been verified by the patient clicking on a link in an email to confirm that they received the verification email. This does not guarantee that the email address is owned by the patient. Default `false`
opted_in_to_email `optional boolean`	`true` only if the patient as consented to receive emails at this email address. If False, then no emails of any kind can be sent to this address. Default `false`
automatic_recipient `optional boolean`	`true` only if the patient as consented to receive automated emails at this email address. Default `false`

Find

Finds email addresses, using param filters.

Invocation

curl -XGET /v1/email_addresses

GET /v1/email_addresses

[
  {
    "data": [
      {
        "id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd", 
        "email": "developer@welkinhealth.com", 
        "friendly_name": "developer contact", 
        "patient_id": "14492e35-c4e4-4235-8175-aa874321144e", 
        "verified": false, 
        "opted_in_to_email": true, 
        "automatic_recipient": false, 
        "updated_at": "2018-09-12T01:27:32.035940+00:00", 
        "created_at": "2018-09-12T01:27:32.036062+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.728752+00:00", 
        "page[to]": "2019-01-23T01:26:06.728768+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
patient_id `optional guid`	ID of the patient which this email address is associated with.
user_id `optional guid`	(Deprecated) ID of the patient which this email address is associated with.
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

External Ids (provisional)

Welkin APIs and systems communicate via GUIDs. All communications with Welkin's standard API must be made using Welkin's GUIDs. In rare cases, custom integrations are supported by mapping Welkin IDs to a set of external IDs. To learn more about custom integrations, drop us a line.

Model

{
  "id": "76c5662c-1e16-4cfa-bbad-900e721a290b", 
  "resource": "patient", 
  "namespace": "ehr", 
  "external_id": "abc-123", 
  "welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}

param	description
id `guid`	The primary identifier
resource `string`	String name of the resource collection that this ID is associated with. For example `workers`
namespace `string`	Snake cased string seperating mappings of the same Welkin ID to multiple external IDs
external_id `string`	ID of the resource in 3rd party system. Can be any string format
welkin_id `guid`	ID of the resource within Welkin. Must be a valid existing Welkin GUID.

Update

Updates an existing external id.

Invocation

curl -XPUT /v1/external_ids/76c5662c-1e16-4cfa-bbad-900e721a290b -d '{
  "resource": "patient", 
  "namespace": "ehr", 
  "external_id": "abc-123", 
  "welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}'

PUT /v1/external_ids/:id -d { }

{
  "id": "76c5662c-1e16-4cfa-bbad-900e721a290b", 
  "resource": "patient", 
  "namespace": "ehr", 
  "external_id": "abc-123", 
  "welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}

Params

param	description
id `guid`	The primary identifier
resource `optional string`	String name of the resource collection that this ID is associated with. For example `workers`
namespace `optional string`	Snake cased string seperating mappings of the same Welkin ID to multiple external IDs
external_id `optional string`	ID of the resource in 3rd party system. Can be any string format
welkin_id `optional guid`	ID of the resource within Welkin. Must be a valid existing Welkin GUID.

Create

Creates a new external id.

Invocation

curl -XPOST /v1/external_ids -d '{
  "resource": "patient", 
  "namespace": "ehr", 
  "external_id": "abc-123", 
  "welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}'

POST /v1/external_ids -d { }

{
  "id": "76c5662c-1e16-4cfa-bbad-900e721a290b", 
  "resource": "patient", 
  "namespace": "ehr", 
  "external_id": "abc-123", 
  "welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}

Params

param	description
resource `string`	String name of the resource collection that this ID is associated with. For example `workers`
namespace `string`	Snake cased string seperating mappings of the same Welkin ID to multiple external IDs
external_id `string`	ID of the resource in 3rd party system. Can be any string format
welkin_id `guid`	ID of the resource within Welkin. Must be a valid existing Welkin GUID.

Find

Finds external ids, using param filters.

Invocation

curl -XGET /v1/external_ids

GET /v1/external_ids

[
  {
    "data": [
      {
        "id": "76c5662c-1e16-4cfa-bbad-900e721a290b", 
        "resource": "patient", 
        "namespace": "ehr", 
        "external_id": "abc-123", 
        "welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.734376+00:00", 
        "page[to]": "2019-01-23T01:26:06.734391+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
resource `optional string`	String name of the resource collection that this ID is associated with. For example `workers`
namespace `optional string`	Snake cased string seperating mappings of the same Welkin ID to multiple external IDs
external_id `optional string`	ID of the resource in 3rd party system. Can be any string format
welkin_id `optional string`	ID of the resource within Welkin. Must be a valid existing Welkin GUID.
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

File Attachments

Attach uploaded files to specific patient profiles. A single file can be attached to multiple patients.

A timeline event is automatically created when a file is attached to a patient. This timeline event includes the file preview and the attachment type.

Model

{
  "id": "b43694f1-ed2d-4e0d-a9ee-65a7e093efee", 
  "patient_id": "45534dcb-daab-45fe-adbc-c0408664ca14", 
  "worker_id": "8004dca9-391c-422f-b8b3-1997b4747dac", 
  "attachment_type": "x-ray", 
  "description": "Right leg", 
  "file_upload_ids": [
    "efbcc819-f25f-4bf4-afd4-198a035d5340"
  ]
}

param	description
id `guid`	The primary identifier
patient_id `guid`	ID of the patient profile onto which the file will be attached
worker_id `optional string`	ID of the worker who is attaching the file
attachment_type `string`	A label attached to the file. Note, for your implementation of Welkin there may be a predefined set of possible labels.
description `optional string`	Text description or notes about the file being attached
file_upload_ids `list(guid)`	List of file upload IDs to attach to the patient

Get

Retrieves a single file attachment.

Invocation

curl -XGET /v1/file_attachments/b43694f1-ed2d-4e0d-a9ee-65a7e093efee

GET /v1/file_attachments/:id

{
  "id": "b43694f1-ed2d-4e0d-a9ee-65a7e093efee", 
  "patient_id": "45534dcb-daab-45fe-adbc-c0408664ca14", 
  "worker_id": "8004dca9-391c-422f-b8b3-1997b4747dac", 
  "attachment_type": "x-ray", 
  "description": "Right leg", 
  "file_upload_ids": [
    "efbcc819-f25f-4bf4-afd4-198a035d5340"
  ]
}

Params

param	description
id `guid`	The primary identifier

Create

Creates a new file attachment.

Invocation

curl -XPOST /v1/file_attachments -d '{
  "patient_id": "45534dcb-daab-45fe-adbc-c0408664ca14", 
  "worker_id": "8004dca9-391c-422f-b8b3-1997b4747dac", 
  "attachment_type": "x-ray", 
  "description": "Right leg", 
  "file_upload_ids": [
    "efbcc819-f25f-4bf4-afd4-198a035d5340"
  ]
}'

POST /v1/file_attachments -d { }

{
  "id": "b43694f1-ed2d-4e0d-a9ee-65a7e093efee", 
  "patient_id": "45534dcb-daab-45fe-adbc-c0408664ca14", 
  "worker_id": "8004dca9-391c-422f-b8b3-1997b4747dac", 
  "attachment_type": "x-ray", 
  "description": "Right leg", 
  "file_upload_ids": [
    "efbcc819-f25f-4bf4-afd4-198a035d5340"
  ]
}

Params

param	description
patient_id `guid`	ID of the patient profile onto which the file will be attached
worker_id `optional guid`	ID of the worker who is attaching the file
attachment_type `string`	A label attached to the file. Note, for your implementation of Welkin there may be a predefined set of possible labels.
description `optional string`	Text description or notes about the file being attached
file_upload_ids `list(guid)`	List of file upload IDs to attach to the patient

Find

Finds file attachments, using param filters.

Invocation

curl -XGET /v1/file_attachments

GET /v1/file_attachments

[
  {
    "data": [
      {
        "id": "b43694f1-ed2d-4e0d-a9ee-65a7e093efee", 
        "patient_id": "45534dcb-daab-45fe-adbc-c0408664ca14", 
        "worker_id": "8004dca9-391c-422f-b8b3-1997b4747dac", 
        "attachment_type": "x-ray", 
        "description": "Right leg", 
        "file_upload_ids": [
          "efbcc819-f25f-4bf4-afd4-198a035d5340"
        ]
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.739634+00:00", 
        "page[to]": "2019-01-23T01:26:06.739646+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

File Uploads

Upload a file to Welkin. Uploaded files are stored on Amazon S3 and only become visible on a patient profile one they have been attached via the File Attachments api.

File upload is a non-RESTful operation which is conducted at /v1/file_uploads/upload

Model

{
  "id": "efbcc819-f25f-4bf4-afd4-198a035d5340", 
  "mime_type": "image/png", 
  "url": "https://welkin-photos-prod-bdb45be0-464e.s3.amazonaws.com/2ab9791d-86f1-e50?AWSAccessKeyId=ASIA&Expires=153924&x-amz-security-token=FQoGZXdz&Signature=FjSiY"
}

param	description
id `guid`	The primary identifier
mime_type `enum`	MIME type of the file being uploaded. Accepted MINE types: `image/tiff`, `image/jpeg`, `image/png`, `application/pdf`
url `string`	URL of the file, including access tokens, of the file on Amazon S3. Note, the example URL has been truncated for display purposes.

Upload

Accepts the binary data of a file and creates the file upload record.

Invocation

import requests

url = 'https://api.welkinhealth.com/v1/file_uploads/upload'
files = {'file': open('example.png', 'rb'), 'image/png'}

r = requests.post(url, files=files)

POST /v1/file_uploads/upload -d { }

{
    "id": "efbcc819-f25f-4bf4-afd4-198a035d5340",
    "mime_type": "image/png",
    "url": "https://welkin-photos-prod-bdb45be0-464e.s3.amazonaws.com/2ab9791d-86f1-e50?AWSAccessKeyId=ASIA&Expires=153924&x-amz-security-token=FQoGZXdz&Signature=FjSiY"
}

Params

param	description
id `guid`	The primary identifier
mime_type `string`	MIME type of the file being uploaded. Accepted MINE types: `image/tiff`, `image/jpeg`, `image/png`, `application/pdf`
url `string`	URL of the file including access tokens of the file on Amazon s3. Note, the example URL has been truncated for display purposes.

Get

Retrieves a single file upload.

Invocation

curl -XGET /v1/file_uploads/efbcc819-f25f-4bf4-afd4-198a035d5340

GET /v1/file_uploads/:id

{
  "id": "efbcc819-f25f-4bf4-afd4-198a035d5340", 
  "mime_type": "image/png", 
  "url": "https://welkin-photos-prod-bdb45be0-464e.s3.amazonaws.com/2ab9791d-86f1-e50?AWSAccessKeyId=ASIA&Expires=153924&x-amz-security-token=FQoGZXdz&Signature=FjSiY"
}

Params

param	description
id `guid`	The primary identifier

Find

Finds file uploads, using param filters.

Invocation

curl -XGET /v1/file_uploads

GET /v1/file_uploads

[
  {
    "data": [
      {
        "id": "efbcc819-f25f-4bf4-afd4-198a035d5340", 
        "mime_type": "image/png", 
        "url": "https://welkin-photos-prod-bdb45be0-464e.s3.amazonaws.com/2ab9791d-86f1-e50?AWSAccessKeyId=ASIA&Expires=153924&x-amz-security-token=FQoGZXdz&Signature=FjSiY"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.742798+00:00", 
        "page[to]": "2019-01-23T01:26:06.742808+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Integration Tasks (provisional)

This endpoint reports the statuses and resulting errors from the ingestion of data via custom integrations built by Welkin.

Model

{
  "id": "9bf1e295-47f5-4027-a382-008c860694c2", 
  "status": "failed", 
  "patient_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c", 
  "ref_ids": [
    "abc123", 
    "cdf456"
  ], 
  "job_id": "8bf1e295-4944-1027-d382-0c36846acd4c", 
  "task_name": "kiwihealth_pull.process_item", 
  "updated_at": "2018-09-12T01:27:32.041332+00:00", 
  "created_at": "2018-09-12T01:27:32.041464+00:00", 
  "errors": [
    {
      "code": "patient_not_found", 
      "message": "There is no patient with that ID."
    }
  ]
}

param	description
id `guid`	The primary identifier
status `enum`	Status of the task. Possible options are, `unattempted`, `running`, `failed`, or `succeeded`
patient_id `guid`	The ID of the patient
ref_ids `array string`	Array of external IDs associated with the tasks, linking the task to the resource in external systems.
job_id `string`	Groups related tasks together
task_name `string`	The name of the task prefixed by the name of the job
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created
errors `array integration-errors`	Array of all the errors that resulted from this specific task. Note, these errors do not roll up to parent tasks.

Model integration-errors

field	type	description
code	`string`	Machine readable error code. The set of possible errors is defined during custom implementation. Examples include: `patient_not_found` or `customer_disabled`
message	`string`	The display message associated with the error code
extra	`string`	JSON blob of information related to this error

Integration jobs

An integration job is a series of tasks all linked together with a common job id.

The following describes an example of a custom integration, and how a job can be structured and reported.

Kiwi Health is an external system that sends patient data to Welkin through a custom integration. When new data is available for Welkin to consume, Kiwi Health sends Welkin a notification. Welkin then validates the notification, fetches the data, and processes it.

A custom integration job could be structured as follows:

kiwihealth_pull.run_kiwihealth_pull
- kiwihealth_pull.validate_patient
- kiwihealth_pull.fetch_results
- kiwihealth_pull.process_response
  - kiwihealth_pull.process_item (potentially multiple process_item tasks)

The top-level task (run_kiwihealth_pull) reports the status of the entire job, not the individual tasks linked to the job. Individual task statuses are reported by task, but any errors they encounter can cause the whole job to fail.

Get

Retrieves a single integration task.

Invocation

curl -XGET /v1/integration_tasks/9bf1e295-47f5-4027-a382-008c860694c2

GET /v1/integration_tasks/:id

{
  "id": "9bf1e295-47f5-4027-a382-008c860694c2", 
  "status": "failed", 
  "patient_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c", 
  "ref_ids": [
    "abc123", 
    "cdf456"
  ], 
  "job_id": "8bf1e295-4944-1027-d382-0c36846acd4c", 
  "task_name": "kiwihealth_pull.process_item", 
  "updated_at": "2018-09-12T01:27:32.041332+00:00", 
  "created_at": "2018-09-12T01:27:32.041464+00:00", 
  "errors": [
    {
      "code": "patient_not_found", 
      "message": "There is no patient with that ID."
    }
  ]
}

Params

param	description
id `guid`	The primary identifier

Find

Finds integration tasks, using param filters.

Invocation

curl -XGET /v1/integration_tasks

GET /v1/integration_tasks

[
  {
    "data": [
      {
        "id": "9bf1e295-47f5-4027-a382-008c860694c2", 
        "status": "failed", 
        "patient_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c", 
        "ref_ids": [
          "abc123", 
          "cdf456"
        ], 
        "job_id": "8bf1e295-4944-1027-d382-0c36846acd4c", 
        "task_name": "kiwihealth_pull.process_item", 
        "updated_at": "2018-09-12T01:27:32.041332+00:00", 
        "created_at": "2018-09-12T01:27:32.041464+00:00", 
        "errors": [
          {
            "code": "patient_not_found", 
            "message": "There is no patient with that ID."
          }
        ]
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.747827+00:00", 
        "page[to]": "2019-01-23T01:26:06.747840+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
job_id `optional string`	Groups related tasks together
task_name `optional string`	The name of the task prefixed by the name of the job
ref_id `optional string`
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Patients

Patients are the primary data object within Welkin. Almost all other data is attached to a patient. Emails, assessment responses, care flows, and many more resources are mapped directly to a specific patient.

There are no restrictions on patient data, so it's possible for duplicates to be created-on purpose or by accident. Take care to ensure you are not duplicating a patient when creating a new one.

When using the Welkin API it's best to designate one system as the master system, and have the other systems be followers. In this model, patients are created in only one source, limiting the possibility of duplicate patient generation.

Model

{
  "id": "45ceeba9-4944-43d1-b34d-0c36846acd4c", 
  "phase": "intake", 
  "primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054", 
  "timezone": "US/Pacific", 
  "first_name": "Grace", 
  "last_name": "Hopper", 
  "birthday": "1906-12-09", 
  "gender": "Female", 
  "height": "72", 
  "primary_language": "english", 
  "smokes": "false", 
  "weight": "175", 
  "street": "3265 17th St", 
  "street_line_two": "#304", 
  "city": "San Francisco", 
  "county": "San Francisco County", 
  "zip_code": "94110", 
  "state": "CA", 
  "country": "US", 
  "updated_at": "2018-09-12T01:27:32.108773+00:00", 
  "created_at": "2018-09-12T01:27:32.109872+00:00"
}

param	description
id `guid`	The primary identifier
phase `enum`	The phase (or stage) of care that this patient is in. The possible set of phases is defined in Workshop.
primary_worker_id `guid`	ID of the worker who is the primary worker for this patient.
coach_id `guid`	(Deprecated) ID of the worker who is the primary worker for this patient.
timezone `timezone`	Timezone in which this patient lives
first_name `string`	First name of this patient
last_name `string`	Last name of this patient
birthday `isodate`	Date of birth of this patient
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created
street `string`	Street address of this patient
street_line_two `string`	Second line of this patient's street address
city `string`	City of this patient's address
county `string`	County in which this patient lives. If unknown then this can be left out.
zip_code `zip_code`	Zip code of this patient's address in five digit form
state `state`	Two character abbreviation of the state in which this patient resides
country `country`	Country in which this patient lives
primary_language `language`	This patient's primary language. Available options are ["english", "spanish", "vietnamese", "tagalog", "chinese", "arabic", "korean", "punjabi", "russian", "other"]
gender `string`	Gender of this patient
height `string`	The two digit height of this patient in inches.
weight `string`	The weight of this patient in pounds.
smokes `boolean`	`true` or `false` for whether this patient smokes.

Update

Updates an existing patient.

Invocation

curl -XPUT /v1/patients/45ceeba9-4944-43d1-b34d-0c36846acd4c -d '{
  "phase": "intake", 
  "primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054", 
  "timezone": "US/Pacific", 
  "first_name": "Grace", 
  "last_name": "Hopper", 
  "birthday": "1906-12-09", 
  "street": "3265 17th St", 
  "street_line_two": "#304", 
  "city": "San Francisco", 
  "county": "San Francisco County", 
  "zip_code": "94110", 
  "state": "CA", 
  "country": "US", 
  "primary_language": "english", 
  "gender": "Female", 
  "height": "72", 
  "weight": "175", 
  "smokes": "false"
}'

PUT /v1/patients/:id -d { }

{
  "id": "45ceeba9-4944-43d1-b34d-0c36846acd4c", 
  "phase": "intake", 
  "primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054", 
  "timezone": "US/Pacific", 
  "first_name": "Grace", 
  "last_name": "Hopper", 
  "birthday": "1906-12-09", 
  "gender": "Female", 
  "height": "72", 
  "primary_language": "english", 
  "smokes": "false", 
  "weight": "175", 
  "street": "3265 17th St", 
  "street_line_two": "#304", 
  "city": "San Francisco", 
  "county": "San Francisco County", 
  "zip_code": "94110", 
  "state": "CA", 
  "country": "US", 
  "updated_at": "2018-09-12T01:27:32.108773+00:00", 
  "created_at": "2018-09-12T01:27:32.109872+00:00"
}

Params

param	description
id `guid`	The primary identifier
phase `optional provider_code`	The phase (or stage) of care that this patient is in. The possible set of phases is defined in Workshop.
primary_worker_id `optional guid`	ID of the worker who is the primary worker for this patient.
coach_id `optional guid`	(Deprecated) ID of the worker who is the primary worker for this patient.
timezone `optional timezone`	Timezone in which this patient lives
first_name `optional name`	First name of this patient
last_name `optional name`	Last name of this patient
birthday `optional isodatetime`	Date of birth of this patient
street `optional string`	Street address of this patient
street_line_two `optional string`	Second line of this patient's street address
city `optional string`	City of this patient's address
county `optional string`	County in which this patient lives. If unknown then this can be left out.
zip_code `optional string`	Zip code of this patient's address in five digit form
state `optional address_state`	Two character abbreviation of the state in which this patient resides
country `optional country`	Country in which this patient lives
primary_language `optional enum`	This patient's primary language. Available options are ["english", "spanish", "vietnamese", "tagalog", "chinese", "arabic", "korean", "punjabi", "russian", "other"]
gender `optional string`	Gender of this patient
height `optional string`	The two digit height of this patient in inches.
weight `optional string`	The weight of this patient in pounds.
smokes `optional boolean`	`true` or `false` for whether this patient smokes.

Create

Creates a new patient.

Invocation

curl -XPOST /v1/patients -d '{
  "phase": "intake", 
  "primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054", 
  "timezone": "US/Pacific", 
  "first_name": "Grace", 
  "last_name": "Hopper", 
  "birthday": "1906-12-09", 
  "street": "3265 17th St", 
  "street_line_two": "#304", 
  "city": "San Francisco", 
  "county": "San Francisco County", 
  "zip_code": "94110", 
  "state": "CA", 
  "country": "US", 
  "primary_language": "english", 
  "gender": "Female", 
  "height": "72", 
  "weight": "175", 
  "smokes": "false", 
  "external_ids": [
    {
      "external_id": "abc-123", 
      "namespace": "ehr"
    }
  ]
}'

POST /v1/patients -d { }

{
  "id": "45ceeba9-4944-43d1-b34d-0c36846acd4c", 
  "phase": "intake", 
  "primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054", 
  "timezone": "US/Pacific", 
  "first_name": "Grace", 
  "last_name": "Hopper", 
  "birthday": "1906-12-09", 
  "gender": "Female", 
  "height": "72", 
  "primary_language": "english", 
  "smokes": "false", 
  "weight": "175", 
  "street": "3265 17th St", 
  "street_line_two": "#304", 
  "city": "San Francisco", 
  "county": "San Francisco County", 
  "zip_code": "94110", 
  "state": "CA", 
  "country": "US", 
  "updated_at": "2018-09-12T01:27:32.108773+00:00", 
  "created_at": "2018-09-12T01:27:32.109872+00:00"
}

Params

param	description
phase `provider_code`	The phase (or stage) of care that this patient is in. The possible set of phases is defined in Workshop.
primary_worker_id `optional guid`	ID of the worker who is the primary worker for this patient.
coach_id `optional guid`	(Deprecated) ID of the worker who is the primary worker for this patient.
timezone `timezone`	Timezone in which this patient lives
first_name `name`	First name of this patient
last_name `name`	Last name of this patient
birthday `birthday`	Date of birth of this patient
street `optional string`	Street address of this patient
street_line_two `optional string`	Second line of this patient's street address
city `optional string`	City of this patient's address
county `optional string`	County in which this patient lives. If unknown then this can be left out.
zip_code `optional string`	Zip code of this patient's address in five digit form
state `optional address_state`	Two character abbreviation of the state in which this patient resides
country `optional country`	Country in which this patient lives
primary_language `optional enum`	This patient's primary language. Available options are ["english", "spanish", "vietnamese", "tagalog", "chinese", "arabic", "korean", "punjabi", "russian", "other"]
gender `optional string`	Gender of this patient
height `optional string`	The two digit height of this patient in inches.
weight `optional string`	The weight of this patient in pounds.
smokes `optional boolean`	`true` or `false` for whether this patient smokes.
email `optional email`	(Deprecated) Email addresses should be created via the email address endpoint.
external_ids `optional list(object)`	(Provisional) A convenience field which creates a patient and an external id mapping at the same time. The ID of this mapping can be fetched from the external ids endpoint.
phone `optional e164_phone`	(Deprecated) Phone numbers should be created via the phone number endpoint.

Find

Finds patients, using param filters.

Invocation

curl -XGET /v1/patients

GET /v1/patients

[
  {
    "data": [
      {
        "id": "45ceeba9-4944-43d1-b34d-0c36846acd4c", 
        "phase": "intake", 
        "primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054", 
        "timezone": "US/Pacific", 
        "first_name": "Grace", 
        "last_name": "Hopper", 
        "birthday": "1906-12-09", 
        "gender": "Female", 
        "height": "72", 
        "primary_language": "english", 
        "smokes": "false", 
        "weight": "175", 
        "street": "3265 17th St", 
        "street_line_two": "#304", 
        "city": "San Francisco", 
        "county": "San Francisco County", 
        "zip_code": "94110", 
        "state": "CA", 
        "country": "US", 
        "updated_at": "2018-09-12T01:27:32.108773+00:00", 
        "created_at": "2018-09-12T01:27:32.109872+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.778782+00:00", 
        "page[to]": "2019-01-23T01:26:06.778800+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Phone Numbers

Manage the available phone based contact methods for a patient. Phone based contact methods are call and sms.

Each patient phone number has it's own consents and opt in status. When setting the consent flags on a phone number make sure that you have a record of how and when consent was received from the patient.

Model

{
  "id": "c9a72425-f433-4c6c-9d95-4057b25acc2f", 
  "patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f", 
  "phone_number": "+15555555555", 
  "phone_number_type": "landline", 
  "friendly_name": "main number", 
  "verified": false, 
  "opted_in_to_sms": true, 
  "opted_in_to_call_recording": false, 
  "opted_in_to_voicemail": false, 
  "opted_in_to_phone": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.123172+00:00", 
  "created_at": "2018-09-12T01:27:32.123301+00:00"
}

param	description
id `guid`	The primary identifier
patient_id `guid`	The identifier of the patient which this phone number is associated.
user_id `guid`	(Deprecated) The identifier of the patient which this phone number is associated.
phone_number `e164_phone`	The phone number to be associated with the patient. Must be in international, E.164 format. Note, this can be a phone number of the patient, a care giver, or other associated entity.
phone_number_type `enum`	(`cell`, `landline`, `other`)
friendly_name `string`	Name of the phone number to help the worker differentiate between patient phone numbers
verified `boolean`	`true` only if you have confirmed this phone number is owned by the patient by calling this number and confirming the patient's indentity details. Default `false`
opted_in_to_sms `boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving SMS at this number. Default `false`
opted_in_to_call_recording `boolean`	`true` only if the patient has consented verbally, digitally, or in writing to calls at this number being recorded. Default `false`
opted_in_to_voicemail `boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving voicemail at this number. Default `false`
opted_in_to_phone `boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving calls at this number. Default `false`
automatic_recipient `boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving automated SMS messages at this number. Default `false`
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single phone number.

Invocation

curl -XGET /v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f

GET /v1/phone_numbers/:id

{
  "id": "c9a72425-f433-4c6c-9d95-4057b25acc2f", 
  "patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f", 
  "phone_number": "+15555555555", 
  "phone_number_type": "landline", 
  "friendly_name": "main number", 
  "verified": false, 
  "opted_in_to_sms": true, 
  "opted_in_to_call_recording": false, 
  "opted_in_to_voicemail": false, 
  "opted_in_to_phone": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.123172+00:00", 
  "created_at": "2018-09-12T01:27:32.123301+00:00"
}

Params

param	description
id `guid`	The primary identifier

Update

Updates an existing phone number.

Invocation

curl -XPUT /v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f -d '{
  "phone_number": "+15555555555", 
  "phone_number_type": "landline", 
  "friendly_name": "main number", 
  "verified": false, 
  "opted_in_to_sms": true, 
  "opted_in_to_call_recording": false, 
  "opted_in_to_voicemail": false, 
  "opted_in_to_phone": true, 
  "automatic_recipient": false
}'

PUT /v1/phone_numbers/:id -d { }

{
  "id": "c9a72425-f433-4c6c-9d95-4057b25acc2f", 
  "patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f", 
  "phone_number": "+15555555555", 
  "phone_number_type": "landline", 
  "friendly_name": "main number", 
  "verified": false, 
  "opted_in_to_sms": true, 
  "opted_in_to_call_recording": false, 
  "opted_in_to_voicemail": false, 
  "opted_in_to_phone": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.123172+00:00", 
  "created_at": "2018-09-12T01:27:32.123301+00:00"
}

Params

param	description
id `guid`	The primary identifier
phone_number `optional e164_phone`	The phone number to be associated with the patient. Must be in international, E.164 format. Note, this can be a phone number of the patient, a care giver, or other associated entity.
phone_number_type `optional enum`	(`cell`, `landline`, `other`)
friendly_name `optional string`	Name of the phone number to help the worker differentiate between patient phone numbers
verified `optional boolean`	`true` only if you have confirmed this phone number is owned by the patient by calling this number and confirming the patient's indentity details. Default `false`
opted_in_to_sms `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving SMS at this number. Default `false`
opted_in_to_call_recording `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to calls at this number being recorded. Default `false`
opted_in_to_voicemail `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving voicemail at this number. Default `false`
opted_in_to_phone `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving calls at this number. Default `false`
automatic_recipient `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving automated SMS messages at this number. Default `false`

Create

Invocation

curl -XPOST /v1/phone_numbers -d '{
  "patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f", 
  "user_id": "2d93352b-86e9-457e-a4b9-961b04c3aadd", 
  "phone_number": "+15555555555", 
  "phone_number_type": "landline", 
  "friendly_name": "main number", 
  "verified": false, 
  "opted_in_to_sms": true, 
  "opted_in_to_call_recording": false, 
  "opted_in_to_voicemail": false, 
  "opted_in_to_phone": true, 
  "automatic_recipient": false
}'

POST /v1/phone_numbers -d { }

{
  "id": "c9a72425-f433-4c6c-9d95-4057b25acc2f", 
  "patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f", 
  "phone_number": "+15555555555", 
  "phone_number_type": "landline", 
  "friendly_name": "main number", 
  "verified": false, 
  "opted_in_to_sms": true, 
  "opted_in_to_call_recording": false, 
  "opted_in_to_voicemail": false, 
  "opted_in_to_phone": true, 
  "automatic_recipient": false, 
  "updated_at": "2018-09-12T01:27:32.123172+00:00", 
  "created_at": "2018-09-12T01:27:32.123301+00:00"
}

Params

param	description
patient_id `guid`	The identifier of the patient which this phone number is associated.
user_id `optional guid`	(Deprecated) The identifier of the patient which this phone number is associated.
phone_number `e164_phone`	The phone number to be associated with the patient. Must be in international, E.164 format. Note, this can be a phone number of the patient, a care giver, or other associated entity.
phone_number_type `enum`	(`cell`, `landline`, `other`)
friendly_name `optional string`	Name of the phone number to help the worker differentiate between patient phone numbers
verified `optional boolean`	`true` only if you have confirmed this phone number is owned by the patient by calling this number and confirming the patient's indentity details. Default `false`
opted_in_to_sms `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving SMS at this number. Default `false`
opted_in_to_call_recording `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to calls at this number being recorded. Default `false`
opted_in_to_voicemail `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving voicemail at this number. Default `false`
opted_in_to_phone `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving calls at this number. Default `false`
automatic_recipient `optional boolean`	`true` only if the patient has consented verbally, digitally, or in writing to receiving automated SMS messages at this number. Default `false`

Delete

Invocation

curl -XDELETE /v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f

DELETE /v1/phone_numbers/:id

{
  "data": null
}

Params

param	description
id `guid`	The primary identifier

Find

Finds phone numbers, using param filters.

Invocation

curl -XGET /v1/phone_numbers

GET /v1/phone_numbers

[
  {
    "data": [
      {
        "id": "c9a72425-f433-4c6c-9d95-4057b25acc2f", 
        "patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f", 
        "phone_number": "+15555555555", 
        "phone_number_type": "landline", 
        "friendly_name": "main number", 
        "verified": false, 
        "opted_in_to_sms": true, 
        "opted_in_to_call_recording": false, 
        "opted_in_to_voicemail": false, 
        "opted_in_to_phone": true, 
        "automatic_recipient": false, 
        "updated_at": "2018-09-12T01:27:32.123172+00:00", 
        "created_at": "2018-09-12T01:27:32.123301+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.791139+00:00", 
        "page[to]": "2019-01-23T01:26:06.791152+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
patient_id `optional guid`	The identifier of the patient which this phone number is associated.
user_id `optional guid`	(Deprecated) The identifier of the patient which this phone number is associated.
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Sms Messages

SMS Messages can be viewed and created from the conversation view of the Patient profile.

Model

{
  "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00", 
  "updated_at": "2018-09-12T01:27:32.045196+00:00", 
  "created_at": "2018-09-12T01:27:32.045336+00:00"
}

param	description
id `guid`	The primary identifier
patient_id `guid`	ID of the patient who sent or received this message. Must match the patient participant of the conversation.
worker_id `guid`	ID of the worker who sent this message. Note: inbound messages do not have a `worker_id`
conversation_id `guid`	ID of the conversation that contains this message
direction `enum`	Direction of the messsage from the perspective of the worker (`inbound` or `outbound`)
contents `string`	Text of the message
automatically_sent `boolean`	Denotes whether the message was created and sent from Welkin by a worker, or via automated process
sent_at `isodatetime`	Date and time when the message was sent
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single sms message.

Invocation

curl -XGET /v1/sms_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26

GET /v1/sms_messages/:id

{
  "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00", 
  "updated_at": "2018-09-12T01:27:32.045196+00:00", 
  "created_at": "2018-09-12T01:27:32.045336+00:00"
}

Params

param	description
id `guid`	The primary identifier

Create

Create a new message which will be visible in the conversation view of the Patient profile.

Creating an SMS Message will send that message to the patient only if the welkin_send parameter is true. Creating the message resource via this api without setting welkin_send to true only records that the message was sent to the patient.

Invocation

curl -XPOST /v1/sms_messages -d '{
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00"
}'

POST /v1/sms_messages -d { }

{
  "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
  "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
  "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
  "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
  "direction": "inbound", 
  "contents": "Hi Developer, Welcome to Welkin Health.", 
  "automatically_sent": false, 
  "sent_at": "2018-09-12T01:27:32.045046+00:00", 
  "updated_at": "2018-09-12T01:27:32.045196+00:00", 
  "created_at": "2018-09-12T01:27:32.045336+00:00"
}

Params

param	description
patient_id `guid`	ID of the patient who sent or received this message. Must match the patient participant of the conversation.
worker_id `guid`	ID of the worker who sent this message. Note: inbound messages do not have a `worker_id`
conversation_id `guid`	ID of the conversation that contains this message
direction `enum`	Direction of the messsage from the perspective of the worker (`inbound` or `outbound`)
contents `string`	Text of the message
automatically_sent `boolean`	Denotes whether the message was created and sent from Welkin by a worker, or via automated process
sent_at `optional isodatetime`	Date and time when the message was sent
welkin_send `boolean`	Indicates if Welkin should send the message for outbound SMS messages

Find

Finds sms messages, using param filters.

Invocation

curl -XGET /v1/sms_messages

GET /v1/sms_messages

[
  {
    "data": [
      {
        "id": "0adfd8b0-3497-48fc-8ffa-eb2add2cde26", 
        "patient_id": "65ae66fa-d1c0-4b98-bf0a-21cd6090229f", 
        "worker_id": "a1fa82d9-19e0-4114-a6d1-6745f8eaeff0", 
        "conversation_id": "2e045bdd-0083-4341-bc37-9a81d990da31", 
        "direction": "inbound", 
        "contents": "Hi Developer, Welcome to Welkin Health.", 
        "automatically_sent": false, 
        "sent_at": "2018-09-12T01:27:32.045046+00:00", 
        "updated_at": "2018-09-12T01:27:32.045196+00:00", 
        "created_at": "2018-09-12T01:27:32.045336+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.800179+00:00", 
        "page[to]": "2019-01-23T01:26:06.800197+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
patient_id `optional guid`	ID of the patient who sent or received this message. Must match the patient participant of the conversation.
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Workers

Workers have access to the Welkin Portal and provide care to patients.

Workers are assigned to patients as the patient's primary worker via
patient.worker_id

Model

{
  "id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
  "email": "developer@welkinhealth.com", 
  "first_name": "Emily", 
  "last_name": "Smith", 
  "phone_number": "+15555555555", 
  "timezone": "US/Eastern", 
  "gender": "Transgender", 
  "roles": "CDE", 
  "updated_at": "2018-09-12T01:27:32.125123+00:00", 
  "created_at": "2018-09-12T01:27:32.125229+00:00"
}

param	description
id `guid`	The primary identifier
email `string`	Email address of the worker. This is also used as the username of the worker when logging into the Welkin Portal.
first_name `string`	Worker's first name
last_name `string`	Worker's last name
phone_number `string`	Direct line phone number of the worker in international, E.164 format.
timezone `string`	Timezone in which the worker's working hours should be represented
gender `string`	Gender of the worker. Possible values are, `Male`, `Female`, `Unknown`, `Other`, `Transgender`, and `Decline`
roles `enum`	The roles of this worker. Possible roles are defined in Workshop.
updated_at `isodatetime`	Datetime the resource was last updated
created_at `isodatetime`	Datetime the resource was created

Get

Retrieves a single worker.

Invocation

curl -XGET /v1/workers/0d5de756-cdda-4cc0-9cca-bcdc36b1a92f

GET /v1/workers/:id

{
  "id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
  "email": "developer@welkinhealth.com", 
  "first_name": "Emily", 
  "last_name": "Smith", 
  "phone_number": "+15555555555", 
  "timezone": "US/Eastern", 
  "gender": "Transgender", 
  "roles": "CDE", 
  "updated_at": "2018-09-12T01:27:32.125123+00:00", 
  "created_at": "2018-09-12T01:27:32.125229+00:00"
}

Params

param	description
id `guid`	The primary identifier

Find

Finds workers, using param filters.

Invocation

curl -XGET /v1/workers

GET /v1/workers

[
  {
    "data": [
      {
        "id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f", 
        "email": "developer@welkinhealth.com", 
        "first_name": "Emily", 
        "last_name": "Smith", 
        "phone_number": "+15555555555", 
        "timezone": "US/Eastern", 
        "gender": "Transgender", 
        "roles": "CDE", 
        "updated_at": "2018-09-12T01:27:32.125123+00:00", 
        "created_at": "2018-09-12T01:27:32.125229+00:00"
      }
    ], 
    "meta": {
      "current": {
        "page[from]": "2019-01-23T01:26:06.805102+00:00", 
        "page[to]": "2019-01-23T01:26:06.805114+00:00", 
        "page[size]": 50
      }
    }
  }
]

Params

param	description
page[from] `optional isodatetime`	The earliest timestamp to include in the response
page[to] `optional isodatetime`	The latest timestamp to include in the response
page[size] `optional integer`	Maximum number of items to include in the response

Additional Information

Types

type	definition	example
boolean	JSON style boolean	`true`
email	`string` representing an email address	`"support@welkinhealth.com"`
enum	`string` with predefined set of values (also known as an enumeration)	`"Female"`
guid	`string` with 36 characters separated into groups by dashes 8-4-4-4-12.	`"45ceeba9-4944-43d1-b34d-0c36846acd4c"`
integer	Counting numbers with no decimal place including zero and negative numbers	`42`
isodatetime	`string` following isodatetime format representing a date and time in UTC	`"2018-09-15T15:20:01"`
isodate	`string` following the isodatetime format representing a day in the local timezone of the worker or patient	`"2018-09-15"`
json	`string` following JSON format. Welkin may require the `json` to have a specific format depending on API endpoint.	`"{"foo": "bar"}"`
list(x)	JSON list of objects of type `x`	`["a", "b", "c"]`
e164_phone	`string` representing an international, E.164 formatted phone number without extensions or other dialing information. Country code must be included.	`"+15555551234"`
state	`string` of the capitalized two character United States state abbreviation	`"CA"`
string	Any quoted set of ASCII characters with no length restriction	`"Welcome to Welkin's APIs"`
timezone	`string` following iana tz format	`"US/Pacific"`
zip_code	`string` of a five digit United States zip code	`"94110"`

Errors

Requests to the common apis are transactional. Any errors that occur in the course of serving a request will fail the operation. In the case of failure, errors will be collected in the errors key in the following format

field	Meaning
status `int`	The http status code of the error. If client logic relies on this value, consider using the response's top-level http status code instead (more below).
code `string`	A string identifier of the welkin-specific error. Refer to the table below.
title `string`	A human-readable title explaining the class of error.
detail `string`	A human-readable description of the specific error instance.
extra `json`	Optional values that provide additional context on the failure.

  {
    "errors": [{
      "status": 400,
      "code": "parse_exception",
      "title": "Parse Exception",
      "detail": "Failed to parse guid at .id",
      "extra": {
        "path": ".id"
      }
    }]
  }

Note that each error is assigned both an integer status and a string code. The code strings represent stable identifiers for welkin-specific errors. Each code string offers a more detailed classification of the error response than an http status allows. A list of common welkin error codes, and their corresponding http status is shown below:

Welkin Code	Http Status	Description
parse_exception	400	The json body of the request is invalid.
uniqueness_exception	400	The request attempted to create a duplicate resource.
bad_request	400	The request is invalid for other reasons.
unauthorized	401	The credentials used for the request are invalid.
forbidden	403	The requester does not have access.
not_found	404	The route or resource requested does not exist.
resource_not_found	404	One or multiple secondary resources could not be found.
internal_server_error	500	Welkin failed to process the request. We're looking into it.

When handling welkin errors, it is correct to use the http status code of the response OR the string codes of individual errors, depending on the needs of the client code. While the body of the response can contain multiple errors, the http response will always have a single integer status code, indicating the primary cause of failure.