NAV Navbar

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

Example token fetch (PYTHON)

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')

Example token usage (PYTHON)

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:

  1. Alex, a worker, logs into Welkin and updates the phone number in the patient's (Allison) profile.
  2. Welkin sends a notification to the customer’s 3rd party system, letting them know that the patient object for Allison has been changed.
  3. In response, the 3rd party system requests the full patient object for Allison, which contains the new phone number.
  4. The system processes the updated patient object and saves it.
  5. 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.

Example notification request body (JSON)

[ { "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

Example Request

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

Example Response

{
  "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

Example Request

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

GET /v1/app_messages/:id

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/app_messages

GET /v1/app_messages

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/assessment_responses/:id

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/assessment_responses

GET /v1/assessment_responses

Example Response

[
  {
    "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.

Model

Example Response

{
  "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

Example Request

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

GET /v1/calendar_events/:id

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/calendar_events

GET /v1/calendar_events

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/calendars/:id

Example Response

{
  "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

Example Request

curl -XGET /v1/calendars

GET /v1/calendars

Example Response

[
  {
    "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

Example Request

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

GET /v1/care_flows/:id

Example Response

{
  "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

Example Request

curl -XGET /v1/care_flows

GET /v1/care_flows

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/conversations/:id

Example Response

{
  "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

Example Request

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

POST /v1/conversations -d { }

Example Response

{
  "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

Example Request

curl -XGET /v1/conversations

GET /v1/conversations

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/custom_data_type_records/:id

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/custom_data_type_records

GET /v1/custom_data_type_records

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/email_addresses/:id

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/email_addresses

GET /v1/email_addresses

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/external_ids

GET /v1/external_ids

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/file_attachments/:id

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/file_attachments

GET /v1/file_attachments

Example Response

[
  {
    "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.

Model

Example Response

{
  "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

Example Request (Python)

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 { }

Example Response

{
    "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

Example Request

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

GET /v1/file_uploads/:id

Example Response

{
  "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

Example Request

curl -XGET /v1/file_uploads

GET /v1/file_uploads

Example Response

[
  {
    "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

Example Response

{
  "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:

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

Example Request

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

GET /v1/integration_tasks/:id

Example Response

{
  "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

Example Request

curl -XGET /v1/integration_tasks

GET /v1/integration_tasks

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/patients

GET /v1/patients

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/phone_numbers/:id

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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 { }

Example Response

{
  "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

Example Request

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

DELETE /v1/phone_numbers/:id

Example Response

{
  "data": null
}

Params

param description
id
guid
The primary identifier

Find

Finds phone numbers, using param filters.

Invocation

Example Request

curl -XGET /v1/phone_numbers

GET /v1/phone_numbers

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/sms_messages/:id

Example Response

{
  "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.

Invocation

Example Request

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 { }

Example Response

{
  "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

Example Request

curl -XGET /v1/sms_messages

GET /v1/sms_messages

Example Response

[
  {
    "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

Example Response

{
  "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

Example Request

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

GET /v1/workers/:id

Example Response

{
  "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

Example Request

curl -XGET /v1/workers

GET /v1/workers

Example Response

[
  {
    "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.

Example Response

  {
    "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.