NAV Navbar
python javascript shell

Data API 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

import arrow
import jwt
import requests
JWT_BEARER_URI = 'urn:ietf:params:oauth:grant-type:jwt-bearer'
def get_welkin_api_token(client_id, client_secret, scope, endpoint):
claim = {
'iss': client_id,
'aud': endpoint,
'exp': arrow.utcnow().shift(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_welkin_api_token('<client_id>',
'<client_secret>',
'<list of space separated scopes>',
# example scope string: 'calls.read patients.write'
'https://api.welkinhealth.com/v1/token')
const axios = require('axios');
const jwt_simple = require('jwt-simple');
const querystring = require('querystring');
const JWT_BEARER_URI = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
const WELKIN_TOKEN_URL = 'https://api.welkinhealth.com/v1/token';
const WELKIN_ACCESS_TOKEN = '';
function get_welkin_api_token(client_id, client_secret, scope, endpoint) {
const token_data = {
'iss': client_id,
'aud': endpoint,
'exp': Math.round(new Date() / 1000) + 3600, // one hour token request
'scope': scope,
}
const token = jwt_simple.encode(token_data, , 'HS256');
try {
const res = await axios({
method: 'post',
url: endpoint,
data: querystring.stringify(
{'assertion': token.toString(),
'grant_type': JWT_BEARER_URI
}
)
});
return res.data.access_token;
} catch (e) {
console.log('error could not get access token');
return '';
}
}
WELKIN_ACCESS_TOKEN = get_welkin_api_token(process.env.WELKIN_CLIENT_ID,
process.env.WELKIN_SECRET,
'<list of space separated scopes',
// example scope string: 'calls.read patients.write'
WELKIN_TOKEN_URL);
CURL example not available

Example token usage

import requests
headers = {"Authorization": "Bearer <token>"}
resp = requests.get("https://api.welkinhealth.com/v1/patients", headers=headers).json()
const axios = require('axios');
const headers = {'Authorization': 'Bearer <token>'}
const url = 'https://api.welkinhealth.com/v1/patients';
try {
const res = await axios.get(url, {headers: headers});
const data = res.data.data;
} catch (e) {
console.log("couldn't get data from Welkin");
}
# no shell example for JWT construction
# POST with form-urlencoded body
curl https://api.welkinhealth.com/v1/token -X POST -d 'assertion=eyJ.........OmU&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer'
# POST with json body
curl https://api.welkinhealth.com/v1/token -X POST -d ''

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.

Authentication Steps:

  1. Get access to Integration Tools (requires a Welkin Workshop login).
  2. Create a Client and an associated Credential.
  3. Select the scopes that the Client can request.
  4. Exchange Client Credential for an Access Token as shown in the example code.
  5. Make API requests with the Access Token.

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

The Access Tokens expire after 1 hour and a new Access Token must be requested.

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

Token endpoint: https://api.welkinhealth.com/v1/token

Expected JWT fields

  • iss = Your client_id as issued by Welkin in Integration Tools
  • aud = https://api.welkinhealth.com/v1/token
  • exp = ISO timestamp when the token should expire (recommended 1 hours from current time)
  • scope = A space separated string of scopes

Expected body fields

  • assertion = JWT token
  • grant_type = urn:ietf:params:oauth:grant-type:jwt-bearer

The body may be form-encoded or JSON.

Scopes

Scopes limit the types of data and actions that Client can take via the API. Scopes are passed as a space separated list when requesting an Access Token. For example: calls.read patients.write assessments.read

Each resources has a read and a write scope.

If you make a POST or PUT request with an access token which has only write scopes, you will receive a response with only the ID of the created or modified record. The rest of the fields will be redacted since you don't have read scope.

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 sent every 60 seconds. This means that notifications might be sent at most 60 seconds from the time the resource is changed in Welkin.

Welkin will only send notifications for updates which have happened in the last 24 hours. If you pause webhook delivery for more than 24 hours, or webhook delivery fails for more than 24 hours, you should use Find endpoints to query for any resources which may have changed since the last webhook you received.

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.

Welkin supports two authentication flows for the notifications. Both have the same level of security.

Example Welkin side code (for illustration only)

curl -X POST \
'https://customer.com/notify' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <JWT>' \
-d '[ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ]'
import arrow
import jwt
import requests
# Create the JWT
def create_jwt(client_id, client_secret, notify_url):
claim = {
'iss': client_id,
'aud': notify_url,
'exp': arrow.utcnow().shift(seconds=3600).timestamp,
'scope': 'welkin',
}
assertion = jwt.encode(claim, client_secret, algorithm='HS256')
return assertion
# The token to be used for making notification requests
token = create_jwt('<client_id>',
'<client_secret>',
'<client_notify_url>')
headers = {"Authorization": "Bearer { }".format(token)}
# Metadata about each resource type which has changed
data = [ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ]
# Welkin sends the actual notification
requests.post('<client_notify_url>',
headers=headers,
data=data)
const axios = require('axios');
const jwt_simple = require('jwt-simple');
// Create the JWT
function create_jwt(client_id, client_secret, notify_url) {
const claim = {
'iss': client_id,
'aud': notify_url,
'exp': Math.round(new Date() / 1000) + 3600, // one hour token request
'scope': 'welkin',
}
const assertion = jwt_simple.encode(claim, client_secret, 'HS256');
return assertion;
}
# The token to be used for making notification requests
const token = create_jwt('<client_id>',
'<client_secret>',
'<client_notify_url>')
const headers = {"Authorization": "Bearer " + token};
const data = [ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ];
# Welkin sends the actual notification
try {
const res = await axios({
method: 'post',
url: '<client_notify_url>',
headers: headers,
data: data
});
return res.data.access_token;
} catch (e) {
console.log('error could not get access token');
return '';
}

A JWT is included as the Bearer Token on each notification request.

In this model the JWT is not exchanged for an access token but is used directly as the access token for the notification endpoint.

Expected scope for the notify endpoint: welkin

The JWT audience field will be the same as the notify_url where notifications are being sent.

Hash algorithm used by Welkin in creating the JWT: HS256

To be provided to Welkin:

  • client_id - identifies Welkin in the customer's system
  • client_secret - must be transmitted securely to Welkin
  • notify_url - url at which the customer will receive the webhooks
  • list of api resources for which notifications should be sent

Token exchange

Example Welkin side code (for illustration only)

import arrow
import jwt
import requests
JWT_BEARER_URI = 'urn:ietf:params:oauth:grant-type:jwt-bearer'
# Welkin gets an access token from customer
def get_token(client_id, client_secret, endpoint):
claim = {
'iss': client_id,
'aud': endpoint,
'exp': arrow.utcnow().shift(seconds=3600).timestamp,
'scope': 'welkin',
}
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
# The token to be used for making notification requests
token = get_token('<client_id>',
'<client_secret>',
'<token_endpoint_url>'
)
headers = {"Authorization": "Bearer { }".format(token)}
# Metadata about each resource type which has changed
data = [ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ]
# Welkin sends the actual notification
requests.post('<client_notify_url>',
headers=headers,
data=data)
const axios = require('axios');
const jwt_simple = require('jwt-simple');
// Create the JWT
function create_jwt(client_id, client_secret, notify_url) {
const claim = {
'iss': client_id,
'aud': notify_url,
'exp': Math.round(new Date() / 1000) + 3600, // one hour token request
'scope': 'welkin',
}
const assertion = jwt_simple.encode(claim, , 'HS256');
return assertion;
}
function get_customer_webhook_token(client_id, client_secret, endpoint) {
const token = create_jwt(client_id, client_secret, endpoint);
const JWT_BEARER_URI = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
try {
const res = await axios({
method: 'post',
url: endpoint,
data: querystring.stringify(
{'assertion': token.toString(),
'grant_type': JWT_BEARER_URI
}
)
});
return res.data.access_token;
} catch (e) {
console.log('error could not get access token');
return '';
}
}
const token = get_customer_webhook_token("<customer client id>",
"<customer client secret>",
"<customer token url>");
const headers = {"Authorization": "Bearer " + token};
const data = [ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ];
# Welkin sends the actual notification
try {
const res = await axios({
method: 'post',
url: '<client_notify_url>',
headers: headers,
data: data
});
return res.data.access_token;
} catch (e) {
console.log('error could not get access token');
return '';
}
CURL example not available

A JWT sent as a Bearer Token to your Token endpoint is exchanged for an access token which is then used when sending the notifications.

In this model we send two requests, first to get an access token and then to send the notification. Having two round trip requests is not needed to secure the notifications endpoint.

Expected scope for the notify endpoint: welkin

The JWT audience field will be the same as the token_endpoint_url where the JWT is exchanged for an access token.

Hash algorithm used by Welkin in creating the JWT: HS256

To be provided to Welkin:

  • client_id - identifies Welkin in the customer's system
  • client_secret - must be transmitted securely to Welkin
  • notify_url - url at which the customer will receive the webhooks
  • token_endpoint_url - url from which Welkin will request access tokens
  • list of api resources for which notifications should be sent

Example request for access token from Welkin to Customer

curl -X POST \
'https://customer.com/token' \
-H 'Content-Type: application/json' \
-d '{ "assertion": "<JWT>",
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
}'
const axios = require('axios');
const jwt_simple = require('jwt-simple');
const querystring = require('querystring');
const JWT_BEARER_URI = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
function get_customer_webhook_token(client_id, client_secret, endpoint) {
const token_data = {
'iss': client_id,
'aud': endpoint,
'exp': Math.round(new Date() / 1000) + 3600, // one hour token request
'scope': 'welkin',
}
const token = jwt_simple.encode(token_data, , 'HS256');
try {
const res = await axios({
method: 'post',
url: endpoint,
data: querystring.stringify(
{'assertion': token.toString(),
'grant_type': JWT_BEARER_URI
}
)
});
return res.data.access_token;
} catch (e) {
console.log('error could not get access token');
return '';
}
}
get_customer_webhook_token("<customer client id>",
"<customer client secret>",
"<customer token url>");
import arrow
import jwt
import requests
JWT_BEARER_URI = 'urn:ietf:params:oauth:grant-type:jwt-bearer'
def get_customer_webhook_token(client_id, client_secret, endpoint):
claim = {
'iss': client_id,
'aud': endpoint,
'exp': arrow.utcnow().shift(seconds=3600).timestamp,
'scope': 'welkin',
}
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_customer_webhook_token('<customer client id>',
'<customer client secret>',
'<customer token url>')

Example token response from Customer

{
"access_token": "<token>"
}

Example notification from Welkin to Customer (url truncated)

curl -X POST \
'https://customer.com/notify' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '[ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ]'
import requests
headers = {"Authorization": "Bearer { }".format("<token from exchange>")}
# Metadata about each resource type which has changed
data = [ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ]
# Welkin sends the actual notification
requests.post('<client_notify_url>',
headers=headers,
data=data)
const axios = require('axios');
const headers = {"Authorization": "Bearer " + "<token from exchange>"};
// Metadata about each resource type which has changed
const data = [ { "resource": "patients",
"from": "2018-05-14T23:34:05.647496",
"to": "2018-05-15T23:35:05.647496",
"href": "https://api.welkinhealth.com/v1/patients ..." } ];
const response = await axios({method: 'post', url: '<client_notify_url>', headers: headers, data: data});

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
const axios = require('axios');
const url = 'https://api.welkinhealth.com/v1/patients?page[from]=2018-06-15T10:30:01&page[to]=2018-09-30T10:29:59&page[size]=10';
function get_by_post() {
try {
const res = await axios({
method: 'get',
url: url
});
return res.data;
} catch (e) {
console.log('error could not get data from Welkin');
return '';
}
}
import requests
url = 'https://api.welkinhealth.com/v1/patients?page[from]=2018-06-15T10:30:01&page[to]=2018-09-30T10:29:59&page[size]=10'
headers = {"Authorization": "Bearer { }".format(<access_token>)}
response = requests.get(url, headers=headers)

Example Response

{
"data": [
{
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"first_name": "Grace",
"last_name": "Hopper",
"updated_at": "2018-09-12T01:27:32.108773+00:00",
"created_at": "2018-09-12T01:27:32.109872+00:00"
}
],
"links": {
"href": {
"current": "https://api.welkinhealth.com/v1/patients?resource_name=patients&page[size]=50&page[%5B]from]=2018-06-15T10:30:01",
"next": "https://api.welkinhealth.com/v1/patients?resource_name=patients&page[size]=50&page[%5B]from]=2018-07-13T21:56:43"
},
"current": {
"href": "https://api.welkinhealth.com/v1/patients?resource_name=patients&page[size]=50&page[%5B]from]=2018-06-15T10:30:01",
"meta": {
"page[to]": "2018-09-30T10:29:59+00:00",
"page[size]": 50,
"page[from]": "2018-06-15T10:30:01"
}
},
"meta": {
"current": {
"page[to]": "2018-09-30T10:29:59+00:00",
"page[size]": 50,
"page[from]": "2018-06-15T10:30:01"
},
"next": {
"page[to]": "2018-09-30T10:29:59+00:00",
"page[size]": 50,
"page[from]": "2018-07-13T21:56:43"
}
},
"next": {
"href": "https://api.welkinhealth.com/v1/patients?resource_name=patients&page[size]=50&page[%5B]from]=2018-07-13T21:56:43",
"meta": {
"page[to]": "2018-09-30T10:29:59+00:00",
"page[size]": 50,
"page[from]": "2018-07-13T21:56:43"
}
}
}
}

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 you need data from a specific time range you should use the Find endpoints to pull data for the specific time range.

Find URLs are sent as part of Update Notifications


If a record has been modified multiple times it will only be returned by the Find endpoint once. It will be included in the page of results that encompass the records current updated_at time.

For example:

  • 10/1/19 10:00 AM, New patient created.
  • 10/1/19 11:00 AM, Patient address updated in UI.
  • 10/1/19 11:05 AM, Patient address updated again in UI.

Find will only return one record for the above patient in the page encompassing 10/1/19 11:05 AM.


Data is paginated and the links section of the response indicates how to navigate the pagination. Making a GET request on the next url will give you next batch of results. There will be a next URL until you reach the end of the results for your Find query.

Make sure to fully follow the pagination links when receiving Update Notifications to ensure you load all the data.

Full links fields are elided in each FIND example response below for each method.

Find by POST

Example Request

curl -XPOST /v1/phone_numbers/find -d '{
"phone_number"="+15555555555",
"page[from]"=2018-06-15T10:30:01,
"page[to]"=2018-09-30T10:29:59,
"page[size]"=10
}'
const axios = require('axios');
const data = {"phone_number": "+15555555555",
"page[from]": "2018-06-15T10:30:01",
"page[to]": "2018-09-30T10:29:59",
"page[size]": "10"
};
const url = 'https://api.welkinhealth.com/v1/phone_numbers/find';
function get_by_post() {
try {
const res = await axios({
method: 'post',
url: url,
data: data
});
return res.data;
} catch (e) {
console.log('error could not get data from Welkin');
return '';
}
}
import requests
url = 'https://api.welkinhealth.com/v1/phone_numbers/find'
headers = {"Authorization": "Bearer { }".format(<access_token>)}
data = {"phone_number": "+15555555555",
"page[from]": "2018-06-15T10:30:01",
"page[to]": "2018-09-30T10:29:59",
"page[size]": "10"
}
response = requests.post(url,
headers=headers,
data=data)

Security best practices dictate keeping PII and PHI out of URLs (in the path or in query parameters) because information in URLs can be inadvertently exposed via client, network, proxy and server logs and other mechanisms.

Accordingly, Welkin supports sending sensitive API parameters as a part of a POST body for performing find actions. This is accomplished via the Find By Post methods of this API.

The Find By Post request URL is /v1/<resource_type>/find

Parameters for Find By Post requests are sent in the request body.

API Reference

Alerts

Model

Example Response

param description
id
guid
The primary identifier of the alerts record.
patient_id
guid
worker_id
guid
alert_type
string
config
json
active_time
isodatetimestring
finished_time
isodatetime
completed
boolean
dismissed
dismissed_by_worker_id

Get

Retrieves a single alert by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/alerts/45ceeba9-4944-43d1-b34d-0c36846acd4c -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/alerts/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/alerts/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/alerts/:id

Required Scope

alerts.read or all

Example Response

{
"data":
}

Params

param description
id
guid
The primary identifier of the alerts record.

Create

Creates a new alert.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/alerts -d '{
"patient_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"worker_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"alert_type": "some_string"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"patient_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"worker_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"alert_type": "some_string"
}
url = 'https://api.welkinhealth.com/v1/alerts'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/alerts';
const data = {
"patient_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"worker_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"alert_type": "some_string"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/alerts -d { }

Required Scope

alerts.write or all

Example Response

{
"data":
}

Params

param description
patient_id
guid
worker_id
guid
alert_type
string
config
json
active_time
isodatetimestring

Update

Updates an existing alert.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/v1/alerts/45ceeba9-4944-43d1-b34d-0c36846acd4c -d '{
"finished_time": "2018-10-21T18:30:10.100000+00:00"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"finished_time": "2018-10-21T18:30:10.100000+00:00"
}
url = 'https://api.welkinhealth.com/v1/alerts/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/alerts/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const data = {
"finished_time": "2018-10-21T18:30:10.100000+00:00"
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

alerts.write or all

Example Response

{
"data":
}

Params

param description
id
guid
The primary identifier of the alerts record.
config
json
active_time
isodatetimestring
finished_time
isodatetime
completed
boolean

Find

Retrieves alerts, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the alerts resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/alerts -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/alerts'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/alerts';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/alerts

Required Scope

alerts.read or all

Example Response

{
"data": [
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

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

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 of the app messages record.
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 message 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 by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/app_messages/:id

Required Scope

app_messages.read or all

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

Params

param description
id
guid
The primary identifier of the app messages record.

Create

Creates a new app message.

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

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/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"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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"
}
url = 'https://api.welkinhealth.com/v1/app_messages'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/app_messages';
const data = {
"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"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/app_messages -d { }

Required Scope

app_messages.write or all

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

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 message from the perspective of the worker (inbound or outbound)
contents
string
Text of the message
sent_at
isodatetime
Date and time when the message was sent

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 https://api.welkinhealth.com/v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26 -d '{
"sent_at": "2018-09-12T01:27:32.045046+00:00"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"sent_at": "2018-09-12T01:27:32.045046+00:00"
}
url = 'https://api.welkinhealth.com/v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/app_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26';
const data = {
"sent_at": "2018-09-12T01:27:32.045046+00:00"
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

app_messages.write or all

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

Params

param description
id
guid
The primary identifier of the app messages record.
sent_at
isodatetime
Date and time when the message was sent

Find

Retrieves app messages, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the app messages resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/app_messages -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/app_messages'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/app_messages';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/app_messages

Required Scope

app_messages.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
patient_id
guid
ID of the patient who sent or received this message.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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",
"spec": {
"title": "Survey",
"baseField": {
"fields": [
{
"fields": [
{
"options": [
"SILVER",
"GOLD",
"BRONZE"
],
"fieldId": "plan_type",
"fieldType": "select",
"label": "What is your plan type?"
},
{
"fieldId": "years_active",
"fieldType": "number",
"label": "How long have you had this disease?"
},
{
"allowDecimal": true,
"fieldId": "pain_scale",
"fieldType": "number",
"label": "How much pain on a scale of 1 to 10 do you experience?"
},
{
"fieldId": "last_hcp_visit",
"fieldType": "datepicker",
"label": "When was the last time you visited the hospital?"
},
{
"fieldId": "active",
"fieldType": "boolean",
"label": "Do you have this disease?"
},
{
"fieldId": "insurance_provider",
"fieldType": "textarea",
"label": "What is your insurance provider?"
}
],
"title": "Intake",
"fieldType": "section",
"fieldId": "mySection72"
}
],
"fieldId": "_meta.base_fields",
"fieldType": "base"
},
"id": "789a1bb3-2434-4a8f-8507-38b25438d9f2",
"defaults": {
"wrapper": "assessmentQuestion"
},
"apiResource": "formation_responses"
},
"patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6",
"worker_id": "22dff7c2-eacb-44c0-b562-be6163c31b0f",
"model": {
"insurance_provider": "Acme Insurance",
"plan_type": "SILVER",
"active": true,
"years_active": 2,
"last_hcp_visit": "2018-07-14",
"pain_scale": 0.4
},
"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 of the assessment responses record.
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
guid
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 for whom this assessment was filled out.
worker_id
guid
ID of the worker who created or most recently edited this assessment response. This is only set if the assessment was completed by a worker and not by the patient.
model
json
Response data for assessment fields. The schema for this JSON object can be found in Workshop.
spec
json
Schema of 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 by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/assessment_responses/20c04e56-69f0-4d13-b5c1-a1763abd1218 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/assessment_responses/20c04e56-69f0-4d13-b5c1-a1763abd1218'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/assessment_responses/20c04e56-69f0-4d13-b5c1-a1763abd1218';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/assessment_responses/:id

Required Scope

assessment_responses.read or all

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",
"spec": {
"title": "Survey",
"baseField": {
"fields": [
{
"fields": [
{
"options": [
"SILVER",
"GOLD",
"BRONZE"
],
"fieldId": "plan_type",
"fieldType": "select",
"label": "What is your plan type?"
},
{
"fieldId": "years_active",
"fieldType": "number",
"label": "How long have you had this disease?"
},
{
"allowDecimal": true,
"fieldId": "pain_scale",
"fieldType": "number",
"label": "How much pain on a scale of 1 to 10 do you experience?"
},
{
"fieldId": "last_hcp_visit",
"fieldType": "datepicker",
"label": "When was the last time you visited the hospital?"
},
{
"fieldId": "active",
"fieldType": "boolean",
"label": "Do you have this disease?"
},
{
"fieldId": "insurance_provider",
"fieldType": "textarea",
"label": "What is your insurance provider?"
}
],
"title": "Intake",
"fieldType": "section",
"fieldId": "mySection72"
}
],
"fieldId": "_meta.base_fields",
"fieldType": "base"
},
"id": "789a1bb3-2434-4a8f-8507-38b25438d9f2",
"defaults": {
"wrapper": "assessmentQuestion"
},
"apiResource": "formation_responses"
},
"patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6",
"worker_id": "22dff7c2-eacb-44c0-b562-be6163c31b0f",
"model": {
"insurance_provider": "Acme Insurance",
"plan_type": "SILVER",
"active": true,
"years_active": 2,
"last_hcp_visit": "2018-07-14",
"pain_scale": 0.4
},
"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 of the assessment responses record.
include_schema
boolean
Set 'true', to include assessment schema in the response

Create

Creates a new assessment response.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/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",
"worker_id": "22dff7c2-eacb-44c0-b562-be6163c31b0f",
"model": {
"insurance_provider": "Acme Insurance",
"plan_type": "SILVER",
"active": true,
"years_active": 2,
"last_hcp_visit": "2018-07-14",
"pain_scale": 0.4
},
"title": "some_string"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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",
"worker_id": "22dff7c2-eacb-44c0-b562-be6163c31b0f",
"model": {
"insurance_provider": "Acme Insurance",
"plan_type": "SILVER",
"active": true,
"years_active": 2,
"last_hcp_visit": "2018-07-14",
"pain_scale": 0.4
},
"title": "some_string"
}
url = 'https://api.welkinhealth.com/v1/assessment_responses'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/assessment_responses';
const data = {
"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",
"worker_id": "22dff7c2-eacb-44c0-b562-be6163c31b0f",
"model": {
"insurance_provider": "Acme Insurance",
"plan_type": "SILVER",
"active": true,
"years_active": 2,
"last_hcp_visit": "2018-07-14",
"pain_scale": 0.4
},
"title": "some_string"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/assessment_responses -d { }

Required Scope

assessment_responses.write or all

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",
"spec": {
"title": "Survey",
"baseField": {
"fields": [
{
"fields": [
{
"options": [
"SILVER",
"GOLD",
"BRONZE"
],
"fieldId": "plan_type",
"fieldType": "select",
"label": "What is your plan type?"
},
{
"fieldId": "years_active",
"fieldType": "number",
"label": "How long have you had this disease?"
},
{
"allowDecimal": true,
"fieldId": "pain_scale",
"fieldType": "number",
"label": "How much pain on a scale of 1 to 10 do you experience?"
},
{
"fieldId": "last_hcp_visit",
"fieldType": "datepicker",
"label": "When was the last time you visited the hospital?"
},
{
"fieldId": "active",
"fieldType": "boolean",
"label": "Do you have this disease?"
},
{
"fieldId": "insurance_provider",
"fieldType": "textarea",
"label": "What is your insurance provider?"
}
],
"title": "Intake",
"fieldType": "section",
"fieldId": "mySection72"
}
],
"fieldId": "_meta.base_fields",
"fieldType": "base"
},
"id": "789a1bb3-2434-4a8f-8507-38b25438d9f2",
"defaults": {
"wrapper": "assessmentQuestion"
},
"apiResource": "formation_responses"
},
"patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6",
"worker_id": "22dff7c2-eacb-44c0-b562-be6163c31b0f",
"model": {
"insurance_provider": "Acme Insurance",
"plan_type": "SILVER",
"active": true,
"years_active": 2,
"last_hcp_visit": "2018-07-14",
"pain_scale": 0.4
},
"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
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
Name of the assessment as listed in Workshop
spec_version
guid
Version ID of the assessment as listed in Workshop
patient_id
guid
ID of the patient for whom this assessment was filled out.
worker_id
guid
ID of the worker who created or most recently edited this assessment response. This is only set if the assessment was completed by a worker and not by the patient.
model
json
Response data for assessment fields. The schema for this JSON object can be found in Workshop.
title
string
The title of the assessment to be shown on the patient's timeline.

Find

Retrieves assessment responses, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the assessment responses resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/assessment_responses -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/assessment_responses'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/assessment_responses';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/assessment_responses

Required Scope

assessment_responses.read or all

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",
"spec": {
"title": "Survey",
"baseField": {
"fields": [
{
"fields": [
{
"options": [
"SILVER",
"GOLD",
"BRONZE"
],
"fieldId": "plan_type",
"fieldType": "select",
"label": "What is your plan type?"
},
{
"fieldId": "years_active",
"fieldType": "number",
"label": "How long have you had this disease?"
},
{
"allowDecimal": true,
"fieldId": "pain_scale",
"fieldType": "number",
"label": "How much pain on a scale of 1 to 10 do you experience?"
},
{
"fieldId": "last_hcp_visit",
"fieldType": "datepicker",
"label": "When was the last time you visited the hospital?"
},
{
"fieldId": "active",
"fieldType": "boolean",
"label": "Do you have this disease?"
},
{
"fieldId": "insurance_provider",
"fieldType": "textarea",
"label": "What is your insurance provider?"
}
],
"title": "Intake",
"fieldType": "section",
"fieldId": "mySection72"
}
],
"fieldId": "_meta.base_fields",
"fieldType": "base"
},
"id": "789a1bb3-2434-4a8f-8507-38b25438d9f2",
"defaults": {
"wrapper": "assessmentQuestion"
},
"apiResource": "formation_responses"
},
"patient_id": "81cea8e6-0d47-4af1-8c18-d4019208a8d6",
"worker_id": "22dff7c2-eacb-44c0-b562-be6163c31b0f",
"model": {
"insurance_provider": "Acme Insurance",
"plan_type": "SILVER",
"active": true,
"years_active": 2,
"last_hcp_visit": "2018-07-14",
"pain_scale": 0.4
},
"updated_at": "2018-09-12T01:27:32.024836+00:00",
"created_at": "2018-09-12T01:27:32.025031+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
include_schema
boolean
Set 'true', to include assessment schema in the response
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Audit Logs

An audit trail of logins by users or custom data type modifications performed by a user, api, or process.

Model

Example Response

"data": [
{
"relationships": {},
"event_type": "custom_data",
"event_time": "2020-09-10T23:38:30.851579+00:00",
"created_at": "2020-09-10T23:38:30.854040+00:00",
"updated_at": "2020-09-10T23:38:30.854056+00:00",
"id": "e59b31d9-d854-496d-ab8f-461670a9bc8d",
"actor_type": "worker",
"actor_id": "7e3a8a06-d443-49c4-8ed8-ec1f683e2210",
"env_id": "e88444a4-6ad7-42f9-a9c1-9c7d06d3cdf9",
"type": "audit_logs",
"event": {
"type_name": "cdt_ref_name",
"patient_name": "Test Patient",
"diff": {
"key": "value"
},
"operation": "create",
"patient_id": "802336e8-39df-4243-bb90-d1c7028abdbd",
"id": "24c9fd66-1b15-404c-8668-ea330acb7b81"
}
}
{
"relationships": {},
"event_type": "login",
"event_time": "2020-09-04T17:59:43.322951+00:00",
"created_at": "2020-09-04T17:59:57.332752+00:00",
"updated_at": "2020-09-04T17:59:57.332787+00:00",
"id": "11a1645e-6d31-448b-90e4-4babc662df5a",
"actor_type": "worker",
"actor_id": "1f42jhfb-e2ae-4c91-b7bb-083c956731af",
"env_id": "e88411j4-6ad7-42f9-a9c1-9c7d06d3cdf9",
"type": "audit_logs",
"event": {
"first_name": "Profilio Coach",
"last_name": null,
"id": "1f98adfb-e2ae-4c91-b7bb-083c956731af",
"email": "coach+profilio@welkinhealth.com"
}
}
]
param description
id
guid
The primary identifier of the audit logs record.
env_id
guid
actor_id
guid
actor_type
enum
event_time
isodatetime
event_type
enum
event
json

Get

Retrieves a single audit log by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/audit_logs/ -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/audit_logs/'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/audit_logs/';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/audit_logs/:id

Required Scope

audit_logs.read or all

Example Response

{
"data": [
{
"relationships": {},
"event_type": "login",
"event_time": "2020-09-04T17:59:43.322951+00:00",
"created_at": "2020-09-04T17:59:57.332752+00:00",
"updated_at": "2020-09-04T17:59:57.332787+00:00",
"id": "11a1645e-6d31-448b-90e4-4babc662df5a",
"actor_type": "worker",
"actor_id": "1f42jhfb-e2ae-4c91-b7bb-083c956731af",
"env_id": "e88411j4-6ad7-42f9-a9c1-9c7d06d3cdf9",
"type": "audit_logs",
"event": {
"first_name": "Profilio Coach",
"last_name": null,
"id": "1f98adfb-e2ae-4c91-b7bb-083c956731af",
"email": "coach+profilio@welkinhealth.com"
}
}
]
}

Params

param description
id
guid
The primary identifier of the audit logs record.
event_type
enum
login or custom_data

Find

Retrieves audit logs, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the audit logs resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/audit_logs -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/audit_logs'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/audit_logs';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/audit_logs

Required Scope

audit_logs.read or all

Example Response

{
"data": [
"Elided for simplicity, see Get Endpoints Overview above"
]
}

Params

param description
id
json
The primary identifier of the audit logs record.
actor_type
enum
api, process or worker
event_type
enum
login or custom_data
email
string
For worker actor_type
end_time
date
operation
string
create, update, or delete for custom_data
patient_id
guid
start_time
date
page[from]
date
The earliest timestamp to include in the response
page[to]
date
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Availability

Availability combines a worker's working hours, unavailable times, and calendar events to determine the periods when a worker is available.

Model

Example Response

{
"data": {
"calendar_id": "e9419c29-2980-4488-8559-2e95f7bd78b7",
"worker_id": "c6fb1c46-e6a0-4349-a91d-64a7c2e2d2c9",
"available_times": [
{
"start": "2020-05-27T17:00:00+00:00",
"end": "2020-05-27T19:00:00+00:00"
},
{
"start": "2020-05-27T20:25:00+00:00",
"end": "2020-05-28T00:00:00+00:00"
},
{
"start": "2020-05-28T00:10:00+00:00",
"end": "2020-05-28T01:00:00+00:00"
}
]
}
}
param description
calendar_id
guid
The ID of the calendar.
worker_id
guid
The ID of the worker.
available_times
list
A list of intervals where the worker is available. Each interval is an object containing start and end keys.

Find

Retrieves availability, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the availability resource.

Invocation

Example Request

curl -XGET 'https://api.welkinhealth.com/v1/availability?worker_id=c6fb1c46-e6a0-4349-a91d-64a7c2e2d2c9&start=2020-05-27T07:00:00+00:00&end=2020-05-28T07:00:00+00' -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/availability?worker_id=c6fb1c46-e6a0-4349-a91d-64a7c2e2d2c9&start=2020-05-27T07:00:00+00:00&end=2020-05-28T07:00:00+00'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/availability?worker_id=c6fb1c46-e6a0-4349-a91d-64a7c2e2d2c9&start=2020-05-27T07:00:00+00:00&end=2020-05-28T07:00:00+00';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/availability

Required Scope

availability.read or all

Example Response

{
"data": [
{
"data": {
"calendar_id": "e9419c29-2980-4488-8559-2e95f7bd78b7",
"worker_id": "c6fb1c46-e6a0-4349-a91d-64a7c2e2d2c9",
"available_times": [
{
"start": "2020-05-27T17:00:00+00:00",
"end": "2020-05-27T19:00:00+00:00"
},
{
"start": "2020-05-27T20:25:00+00:00",
"end": "2020-05-28T00:00:00+00:00"
},
{
"start": "2020-05-28T00:10:00+00:00",
"end": "2020-05-28T01:00:00+00:00"
}
]
}
}
]
}

Params

param description
calendar_id
guid
The ID of the calendar for which to find availability. Either this or worker_id must be provided.
worker_id
guid
The ID of the worker for which to find availability. Either this or calendar_id must be provided.
end
isodatetime
Beginning of the time range to examine for worker availability.
start
isodatetime
Beginning of the time range to examine for worker availability.

Calendar Events

Calendar events are appointments on worker calendars. 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": "call",
"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 of the calendar events record.
calendar_id
guid
ID of the calendar on which this event resides
patient_id
guid
ID of the patient :type user_id: guid
user_id
guid
(Deprecated) ID of the patient
is_all_day
true if not scheduled for a specific time of day. false otherwise :type is_all_day: boolean
start_time
isodatetime
Scheduled start time of the calendar event if scheduled for a specific time of day :type start_time: optional isodatetime
end_time
isodatetime
Scheduled end time of the calendar event if scheduled for a specific time of day :type end_time: optional isodatetime
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 or visit)
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 by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/calendar_events/f2baaf15-94d2-415d-b3e6-7409b643d297 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/calendar_events/f2baaf15-94d2-415d-b3e6-7409b643d297'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/calendar_events/f2baaf15-94d2-415d-b3e6-7409b643d297';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/calendar_events/:id

Required Scope

calendar_events.read or all

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": "call",
"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 of the calendar events record.

Create

Creates a new calendar event.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/calendar_events -d '{
"calendar_id": "598de18b-b203-4947-be34-6871188cd81d",
"patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"start_time": "2018-09-10T18:56:19.357228+00:00",
"end_time": "2018-09-10T18:56:19.357540+00:00",
"modality": "call",
"appointment_type": "intake_call"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"calendar_id": "598de18b-b203-4947-be34-6871188cd81d",
"patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"start_time": "2018-09-10T18:56:19.357228+00:00",
"end_time": "2018-09-10T18:56:19.357540+00:00",
"modality": "call",
"appointment_type": "intake_call"
}
url = 'https://api.welkinhealth.com/v1/calendar_events'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/calendar_events';
const data = {
"calendar_id": "598de18b-b203-4947-be34-6871188cd81d",
"patient_id": "509fad6c-5382-4952-ad23-cfc2b2707180",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"start_time": "2018-09-10T18:56:19.357228+00:00",
"end_time": "2018-09-10T18:56:19.357540+00:00",
"modality": "call",
"appointment_type": "intake_call"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/calendar_events -d { }

Required Scope

calendar_events.write or all

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": "call",
"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
guid
ID of the patient :type user_id: guid
user_id
guid
(Deprecated) ID of the patient
start_time
isodatetime
Scheduled start time of the calendar event if scheduled for a specific time of day :type start_time: optional isodatetime
end_time
isodatetime
Scheduled end time of the calendar event if scheduled for a specific time of day :type end_time: optional isodatetime
day
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 or visit)
appointment_type
string
Appointment prompt to be used for this event (see note for details)
ignore_unavailable_times
boolean
If this is set, Welkin will not check whether the calendar event is during an unavailable time for the worker.
ignore_working_hours
boolean
If this is set, Welkin will not check whether the calendar event is within the worker's weekly available days and hours.

Update

Updates an existing calendar event.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/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",
"appointment_type": "intake_call"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"start_time": "2018-09-10T18:56:19.357228+00:00",
"end_time": "2018-09-10T18:56:19.357540+00:00",
"outcome": "completed",
"appointment_type": "intake_call"
}
url = 'https://api.welkinhealth.com/v1/calendar_events/f2baaf15-94d2-415d-b3e6-7409b643d297'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/calendar_events/f2baaf15-94d2-415d-b3e6-7409b643d297';
const data = {
"start_time": "2018-09-10T18:56:19.357228+00:00",
"end_time": "2018-09-10T18:56:19.357540+00:00",
"outcome": "completed",
"appointment_type": "intake_call"
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

calendar_events.write or all

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": "call",
"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 of the calendar events record.
start_time
isodatetime
Scheduled start time of the calendar event if scheduled for a specific time of day :type start_time: optional isodatetime
end_time
isodatetime
Scheduled end time of the calendar event if scheduled for a specific time of day :type end_time: optional isodatetime
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)
appointment_type
string
Appointment prompt to be used for this event (see note for details)
ignore_unavailable_times
boolean
If this is set, Welkin will not check whether the calendar event is during an unavailable time for the worker.
ignore_working_hours
boolean
If this is set, Welkin will not check whether the calendar event is within the worker's weekly available days and hours.

Find

Retrieves calendar events, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the calendar events resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/calendar_events -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/calendar_events'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/calendar_events';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/calendar_events

Required Scope

calendar_events.read or all

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": "call",
"appointment_type": "intake_call",
"updated_at": "2018-09-10T18:56:19.359240+00:00",
"created_at": "2018-09-10T18:56:19.359873+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
calendar_id
guid
The ID of the calendar whose events do you want to find. If the param is not set, then will get all calendar events
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Calendars

Calendars link Calendar Events, coach Unavailable Times, and coach Working Hours 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 of the calendars record.
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 the associated calendar)
created_at
isodatetime
Datetime the resource was created

Get

Retrieves a single calendar by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/calendars/0d5de756-cdda-4cc0-9cca-bcdc36b1a92f -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/calendars/0d5de756-cdda-4cc0-9cca-bcdc36b1a92f'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/calendars/0d5de756-cdda-4cc0-9cca-bcdc36b1a92f';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/calendars/:id

Required Scope

calendars.read or all

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

Params

param description
id
guid
The primary identifier of the calendars record.

Find

Retrieves calendars, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the calendars resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/calendars -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/calendars'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/calendars';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/calendars

Required Scope

calendars.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
email
email
Email address of the worker. This is also used as the username of the worker when logging into the Welkin Portal.
worker
guid
The ID of the worker whose calendar do you want to find
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Calls

Calls record that a call was completed between a worker and a patient. These calls are attached to a calendar event if a call was initiated from a calendar event.

Model

Example Response

{
"id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd",
"call_type": "outbound",
"from_number": "+14155555555",
"to_number": "+15085555555",
"start_time": "2019-03-05T21:03:23.102699+00:00",
"duration": 200,
"calendar_event_id": "cd1483be-e029-4e23-ac8a-b4ebcededb04",
"worker_id": "32f0e2b4-7643-4926-a128-9666c81446cb",
"patient_id": "ee2a33d3-1793-4967-9836-85f68afea893",
"audio_url": "",
"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 of the calls record.
created_at
isodatetime
Datetime the resource was created
updated_at
isodatetime
Datetime the resource was last updated
call_type
enum
The direction of the call. inbound or outbound
from_number
e164_phone
The phone number in E.164 format from which the call orginated.
to_number
e164_phone
The phone number in E.164 format to which the call was placed.
start_time
isodatetime
The datetime when the call was initiated.
duration
integer
The amount of time that the call lasted.
calendar_event_id
guid
The ID of the calendar event from which this call was initiated if the call was started as part of a scheduled calendar event.
worker_id
guid
ID of the worker who participated in the call.
patient_id
guid
ID of the patient who participated in the call.
audio_url
string
URL at which you can listen to the recorded audio of the call if a recording exists.

Get

Retrieves a single call by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/calls/0546cc93-7695-49c1-ab5e-3daf3fde12bd -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/calls/0546cc93-7695-49c1-ab5e-3daf3fde12bd'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/calls/0546cc93-7695-49c1-ab5e-3daf3fde12bd';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/calls/:id

Required Scope

calls.read or all

Example Response

{
"data": {
"id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd",
"call_type": "outbound",
"from_number": "+14155555555",
"to_number": "+15085555555",
"start_time": "2019-03-05T21:03:23.102699+00:00",
"duration": 200,
"calendar_event_id": "cd1483be-e029-4e23-ac8a-b4ebcededb04",
"worker_id": "32f0e2b4-7643-4926-a128-9666c81446cb",
"patient_id": "ee2a33d3-1793-4967-9836-85f68afea893",
"audio_url": "",
"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 of the calls record.

Find

Retrieves calls, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the calls resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/calls -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/calls'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/calls';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/calls

Required Scope

calls.read or all

Example Response

{
"data": [
{
"id": "0546cc93-7695-49c1-ab5e-3daf3fde12bd",
"call_type": "outbound",
"from_number": "+14155555555",
"to_number": "+15085555555",
"start_time": "2019-03-05T21:03:23.102699+00:00",
"duration": 200,
"calendar_event_id": "cd1483be-e029-4e23-ac8a-b4ebcededb04",
"worker_id": "32f0e2b4-7643-4926-a128-9666c81446cb",
"patient_id": "ee2a33d3-1793-4967-9836-85f68afea893",
"audio_url": "",
"updated_at": "2018-09-12T01:27:32.035940+00:00",
"created_at": "2018-09-12T01:27:32.036062+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
calendar_event_id
guid
The ID of the calendar event from which this call was initiated if the call was started as part of a scheduled calendar event.
patient_id
guid
ID of the patient who participated in the call.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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

field description
patient_id
guid
The ID of the patient
id
guid
Description of the overall Care Flow
care_flow
json
A care_flow object
updated_at
isodatetime
Datetime the resource was last updated
created_at
isodatetime
Datetime the resource was created

Model care_flow

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

Model goal

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

Model intervention

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

Get

Retrieves a single care flow by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/care_flows/c68a80d4-95ea-4f61-bf90-615d70bea591 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/care_flows/c68a80d4-95ea-4f61-bf90-615d70bea591'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/care_flows/c68a80d4-95ea-4f61-bf90-615d70bea591';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/care_flows/:id

Required Scope

care_flows.read or all

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

Params

param description
id
guid
The primary identifier of the care flows record.

Find

Retrieves care flows, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the care flows resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/care_flows -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/care_flows'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/care_flows';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/care_flows

Required Scope

care_flows.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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,
"email_address_ids": 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 of the conversations record.
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
email_address_ids
guid
The patient email addresses included in this conversation.
phone_number_id
guid
The ID of the patient's phone number which will be included in this conversation. This ID will be null for email and in-app message conversations.
updated_at
isodatetime
Datetime the resource was last updated
created_at
isodatetime
Datetime the resource was created

Get

Retrieves a single conversation by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/conversations/bfa29e70-e328-4c3b-a3d1-7c2d959735ca -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/conversations/bfa29e70-e328-4c3b-a3d1-7c2d959735ca'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/conversations/bfa29e70-e328-4c3b-a3d1-7c2d959735ca';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/conversations/:id

Required Scope

conversations.read or all

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,
"email_address_ids": 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 of the conversations record.

Create

Create a 3rd party app conversation for a patient

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/conversations -d '{
"patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88",
"conversation_type": "app",
"title": "App"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88",
"conversation_type": "app",
"title": "App"
}
url = 'https://api.welkinhealth.com/v1/conversations'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/conversations';
const data = {
"patient_id": "0de64b35-2d04-40b6-b7a7-ba3d7eb50e88",
"conversation_type": "app",
"title": "App"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/conversations -d { }

Required Scope

conversations.write or all

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,
"email_address_ids": 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
Only app is supported for creating conversations. SMS conversations are created automatically when a phone number is created.
title
string
The title string to be displayed in the conversation view for 3rd party app conversations
email_address_ids
list(guid)
The patient email addresses included in this conversation.

Find

Retrieves conversations, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the conversations resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/conversations -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/conversations'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/conversations';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/conversations

Required Scope

conversations.read or all

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,
"email_address_ids": null,
"updated_at": "2018-09-12T01:27:32.031245+00:00",
"created_at": "2018-09-12T01:27:32.031362+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
patient_id
guid
ID of the patient participant in this conversation. Only one patient can participate in any single conversation.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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 of the custom data type records record.
body
json
The content of the custom data 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 by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/custom_data_type_records/:id

Required Scope

custom_data_type_records.read or all

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

Params

param description
id
guid
The primary identifier of the custom data type records record.

Create

Creates a new custom data type record.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/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"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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"
}
url = 'https://api.welkinhealth.com/v1/custom_data_type_records'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/custom_data_type_records';
const data = {
"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"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/custom_data_type_records -d { }

Required Scope

custom_data_type_records.write or all

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

Params

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

Update

Updates an existing custom data type record.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/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"
}
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"body": {
"name": "Frank Smith",
"suffix": "MD",
"practice_name": "Boston Medical Group",
"office_id": "e32ac52",
"specialty": "internal medicine"
}
}
url = 'https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7';
const data = {
"body": {
"name": "Frank Smith",
"suffix": "MD",
"practice_name": "Boston Medical Group",
"office_id": "e32ac52",
"specialty": "internal medicine"
}
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

custom_data_type_records.write or all

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

Params

param description
id
guid
The primary identifier of the custom data type records record.
body
json
The content of the custom data type record

Delete

Deletes a single custom data type record.

Invocation

Example Request

curl -XDELETE https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7'
resp = requests.delete(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/custom_data_type_records/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7';
const response = await axios({method: 'delete', url: url, headers: headers});

DELETE /v1/custom_data_type_records/:id

Required Scope

custom_data_type_records.write or all

Example Response

{
"data": null
}

Params

param description
id
guid
The primary identifier of the custom data type records record.

Find

Retrieves custom data type records, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the custom data type records resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/custom_data_type_records -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/custom_data_type_records'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/custom_data_type_records';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/custom_data_type_records

Required Scope

custom_data_type_records.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
patient_id
guid
The ID of the patient
type_name
string
ID of the custom data type as defined in Workshop
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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 its 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 of the email addresses record.
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 by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/email_addresses/:id

Required Scope

email_addresses.read or all

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

Params

param description
id
guid
The primary identifier of the email addresses record.

Create

Creates a new email address.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/email_addresses -d '{
"email": "developer@welkinhealth.com",
"friendly_name": "developer contact",
"patient_id": "14492e35-c4e4-4235-8175-aa874321144e",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"verified": false,
"opted_in_to_email": true,
"automatic_recipient": false
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"email": "developer@welkinhealth.com",
"friendly_name": "developer contact",
"patient_id": "14492e35-c4e4-4235-8175-aa874321144e",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"verified": false,
"opted_in_to_email": true,
"automatic_recipient": false
}
url = 'https://api.welkinhealth.com/v1/email_addresses'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/email_addresses';
const data = {
"email": "developer@welkinhealth.com",
"friendly_name": "developer contact",
"patient_id": "14492e35-c4e4-4235-8175-aa874321144e",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"verified": false,
"opted_in_to_email": true,
"automatic_recipient": false
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/email_addresses -d { }

Required Scope

email_addresses.write or all

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

Params

param description
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

Update

Updates an existing email address.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/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
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"email": "developer@welkinhealth.com",
"friendly_name": "developer contact",
"verified": false,
"opted_in_to_email": true,
"automatic_recipient": false
}
url = 'https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd';
const data = {
"email": "developer@welkinhealth.com",
"friendly_name": "developer contact",
"verified": false,
"opted_in_to_email": true,
"automatic_recipient": false
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

email_addresses.write or all

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

Params

param description
id
guid
The primary identifier of the email addresses record.
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
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

Delete

Deletes a single email address.

Invocation

Example Request

curl -XDELETE https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd'
resp = requests.delete(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/email_addresses/0546cc93-7695-49c1-ab5e-3daf3fde12bd';
const response = await axios({method: 'delete', url: url, headers: headers});

DELETE /v1/email_addresses/:id

Required Scope

email_addresses.write or all

Example Response

{
"data": null
}

Params

param description
id
guid
The primary identifier of the email addresses record.

Find

Retrieves email addresses, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the email addresses resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/email_addresses -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/email_addresses'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/email_addresses';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/email_addresses

Required Scope

email_addresses.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
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.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Email Messages

Email messages can be viewed and created from the conversation view of the Patient profile. Email messages can also be sent to patients via this API endpoint. Email messages sent from patients are received and recorded in Welkin when the patient responds.

Model

Example Response

{
"id": "76c5662c-1e16-4cfa-bbad-900e721a290b",
"patient_id": "e6cf56d8-a62d-4581-8339-91c846960041",
"direction": "outbound",
"subject": "This is a test email subject",
"body_text": "This is a sample email body",
"conversation_id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca",
"sender_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f",
"automatically_sent": "false",
"footer": "If you are experiencing a life-threatening emergency, please call 911.",
"sent_at": "2019-10-13T01:32:12.000000+00:00",
"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 of the email messages record.
patient_id
guid
ID of the patient who sent or received this message.
sender_id
guid
The ID of the email sender. When creating an email, this must be a worker ID.
direction
enum
Direction of the message from the perspective of the worker (inbound or outbound)
conversation_id
guid
The conversation that contains this message. This must refer to a conversation with conversation_type "email". The patient_id of a newly created email will be the same as the patient in the conversation.
subject
string
Subject of the message
body_html
html_template
HTML body of the message
body_text
string
Text body of the message
footer
string
The content of the message footer which was appended to the bottom of the message automatically by Welkin before it was sent. This will be blank if footers have not been configured for the Wekin environment being used.
sent_at
isodatatime
The time when the messages was sent. For inbound emails this is the time when Welkin received the message.
automatically_sent
boolean
Denotes whether the message was created and sent by a worker, or via automated process. Only applies to outbound messages.
updated_at
isodatetime
Datetime the resource was last updated
created_at
isodatetime
Datetime the resource was created

Get

Retrieves a single email message by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/email_messages/76c5662c-1e16-4cfa-bbad-900e721a290b -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/email_messages/76c5662c-1e16-4cfa-bbad-900e721a290b'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/email_messages/76c5662c-1e16-4cfa-bbad-900e721a290b';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/email_messages/:id

Required Scope

email_messages.read or all

Example Response

{
"data": {
"id": "76c5662c-1e16-4cfa-bbad-900e721a290b",
"patient_id": "e6cf56d8-a62d-4581-8339-91c846960041",
"direction": "outbound",
"subject": "This is a test email subject",
"body_text": "This is a sample email body",
"conversation_id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca",
"sender_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f",
"automatically_sent": "false",
"footer": "If you are experiencing a life-threatening emergency, please call 911.",
"sent_at": "2019-10-13T01:32:12.000000+00:00",
"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 of the email messages record.

Create

Send an email message through Welkin to the patient.

If you omit body_text or body_html, Welkin will use the other field to populate the missing one.

You can provide an existing conversation_id, or provide a conversation object to batch-create a conversation for this message.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/email_messages -d '{
"sender_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f",
"conversation_id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca",
"subject": "This is a test email subject",
"body_text": "This is a sample email body",
"automatically_sent": "false"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"sender_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f",
"conversation_id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca",
"subject": "This is a test email subject",
"body_text": "This is a sample email body",
"automatically_sent": "false"
}
url = 'https://api.welkinhealth.com/v1/email_messages'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/email_messages';
const data = {
"sender_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f",
"conversation_id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca",
"subject": "This is a test email subject",
"body_text": "This is a sample email body",
"automatically_sent": "false"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/email_messages -d { }

Required Scope

email_messages.write or all

Example Response

{
"data": {
"id": "76c5662c-1e16-4cfa-bbad-900e721a290b",
"patient_id": "e6cf56d8-a62d-4581-8339-91c846960041",
"direction": "outbound",
"subject": "This is a test email subject",
"body_text": "This is a sample email body",
"conversation_id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca",
"sender_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f",
"automatically_sent": "false",
"footer": "If you are experiencing a life-threatening emergency, please call 911.",
"sent_at": "2019-10-13T01:32:12.000000+00:00",
"updated_at": "2018-09-12T01:27:32.033666+00:00",
"created_at": "2018-09-12T01:27:32.033816+00:00"
}
}

Params

param description
sender_id
guid
The ID of the email sender. When creating an email, this must be a worker ID.
conversation_id
guid
The conversation that contains this message. This must refer to a conversation with conversation_type "email". The patient_id of a newly created email will be the same as the patient in the conversation.
subject
string
Subject of the message
body_html
html_template
HTML body of the message
body_text
string
Text body of the message
automatically_sent
boolean
Denotes whether the message was created and sent by a worker, or via automated process. Only applies to outbound messages.

Find

Retrieves email messages, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the email messages resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/email_messages -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/email_messages'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/email_messages';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/email_messages

Required Scope

email_messages.read or all

Example Response

{
"data": [
{
"id": "76c5662c-1e16-4cfa-bbad-900e721a290b",
"patient_id": "e6cf56d8-a62d-4581-8339-91c846960041",
"direction": "outbound",
"subject": "This is a test email subject",
"body_text": "This is a sample email body",
"conversation_id": "bfa29e70-e328-4c3b-a3d1-7c2d959735ca",
"sender_id": "0d5de756-cdda-4cc0-9cca-bcdc36b1a92f",
"automatically_sent": "false",
"footer": "If you are experiencing a life-threatening emergency, please call 911.",
"sent_at": "2019-10-13T01:32:12.000000+00:00",
"updated_at": "2018-09-12T01:27:32.033666+00:00",
"created_at": "2018-09-12T01:27:32.033816+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

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

Event Labels

Event Labels are used to classify the outcome of a call or visit. Workers can label events after they complete either from the timeline or in the prompt shown at the end of the call. Event Labels are available in Welkin's analytics to help track the outcomes of events.

Model

Example Response

{
"id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7",
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4",
"entity_type": "call",
"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 of the event labels record.
body
json
A json object containing label IDs and associated answers. The set of labels and their IDs and valid values are defined in Workshop.
entity_id
guid
The ID of the call or visit which this event label set is attached to.
entity_type
enum
The type of the entity_id object (either call or visit).
created_at
isodatetime
Datetime the resource was created
updated_at
isodatetime
Datetime the resource was last updated

Get

Retrieves a single event label by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/event_labels/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/event_labels/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/event_labels/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/event_labels/:id

Required Scope

event_labels.read or all

Example Response

{
"data": {
"id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7",
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4",
"entity_type": "call",
"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 of the event labels record.

Create

Creates a new event label.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/event_labels -d '{
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4"
}
url = 'https://api.welkinhealth.com/v1/event_labels'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/event_labels';
const data = {
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/event_labels -d { }

Required Scope

event_labels.write or all

Example Response

{
"data": {
"id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7",
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4",
"entity_type": "call",
"updated_at": "2018-09-12T01:27:32.033666+00:00",
"created_at": "2018-09-12T01:27:32.033816+00:00"
}
}

Params

param description
body
json
A json object containing label IDs and associated answers. The set of labels and their IDs and valid values are defined in Workshop.
entity_id
guid
The ID of the call or visit which this event label set is attached to.

Update

Updates an existing event label.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/v1/event_labels/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7 -d '{
"body": {
"welkin_default": "completed",
"follow_up": "no"
}
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"body": {
"welkin_default": "completed",
"follow_up": "no"
}
}
url = 'https://api.welkinhealth.com/v1/event_labels/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/event_labels/07ae21f7-c60e-42cb-ab7a-c80a3c445cc7';
const data = {
"body": {
"welkin_default": "completed",
"follow_up": "no"
}
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

event_labels.write or all

Example Response

{
"data": {
"id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7",
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4",
"entity_type": "call",
"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 of the event labels record.
body
json
A json object containing label IDs and associated answers. The set of labels and their IDs and valid values are defined in Workshop.

Find

Retrieves event labels, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the event labels resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/event_labels -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/event_labels'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/event_labels';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/event_labels

Required Scope

event_labels.read or all

Example Response

{
"data": [
{
"id": "07ae21f7-c60e-42cb-ab7a-c80a3c445cc7",
"body": {
"welkin_default": "completed",
"follow_up": "no"
},
"entity_id": "a162d51e-7791-476a-bf9c-c631e178e3c4",
"entity_type": "call",
"updated_at": "2018-09-12T01:27:32.033666+00:00",
"created_at": "2018-09-12T01:27:32.033816+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

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

External Ids

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": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}
param description
id
guid
The primary identifier of the external ids record.
resource
string
String name of the resource collection that this ID is associated with. For example workers
namespace
string
Snake cased string separating 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.

Get

Retrieves a single external id by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/external_ids/76c5662c-1e16-4cfa-bbad-900e721a290b -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/external_ids/76c5662c-1e16-4cfa-bbad-900e721a290b'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/external_ids/76c5662c-1e16-4cfa-bbad-900e721a290b';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/external_ids/:id

Required Scope

external_ids.read or all

Example Response

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

Params

param description
id
guid
The primary identifier of the external ids record.

Create

Creates a new external id.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/external_ids -d '{
"resource": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"resource": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}
url = 'https://api.welkinhealth.com/v1/external_ids'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/external_ids';
const data = {
"resource": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/external_ids -d { }

Required Scope

external_ids.write or all

Example Response

{
"data": {
"id": "76c5662c-1e16-4cfa-bbad-900e721a290b",
"resource": "calendar_events",
"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 separating 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 https://api.welkinhealth.com/v1/external_ids/76c5662c-1e16-4cfa-bbad-900e721a290b -d '{
"resource": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"resource": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}
url = 'https://api.welkinhealth.com/v1/external_ids/76c5662c-1e16-4cfa-bbad-900e721a290b'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/external_ids/76c5662c-1e16-4cfa-bbad-900e721a290b';
const data = {
"resource": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

external_ids.write or all

Example Response

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

Params

param description
id
guid
The primary identifier of the external ids record.
resource
string
String name of the resource collection that this ID is associated with. For example workers
namespace
string
Snake cased string separating 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

Retrieves external ids, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the external ids resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/external_ids -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/external_ids'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/external_ids';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/external_ids

Required Scope

external_ids.read or all

Example Response

{
"data": [
{
"id": "76c5662c-1e16-4cfa-bbad-900e721a290b",
"resource": "calendar_events",
"namespace": "ehr",
"external_id": "abc-123",
"welkin_id": "e6cf56d8-a62d-4581-8339-91c846960041"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

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 separating 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
string
ID of the resource within Welkin. Must be a valid existing Welkin GUID.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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"
],
"created_at": "2020-06-24T01:27:32.045336+00:00"
}
param description
id
guid
The primary identifier of the file attachments record.
patient_id
guid
ID of the patient profile onto which the file will be attached
worker_id
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
created_at
isodatetime
Date and time when the attachment created

Get

Retrieves a single file attachment by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/file_attachments/b43694f1-ed2d-4e0d-a9ee-65a7e093efee -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/file_attachments/b43694f1-ed2d-4e0d-a9ee-65a7e093efee'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/file_attachments/b43694f1-ed2d-4e0d-a9ee-65a7e093efee';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/file_attachments/:id

Required Scope

file_attachments.read or all

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"
],
"created_at": "2020-06-24T01:27:32.045336+00:00"
}
}

Params

param description
id
guid
The primary identifier of the file attachments record.

Create

Creates a new file attachment.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/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"
]
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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"
]
}
url = 'https://api.welkinhealth.com/v1/file_attachments'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/file_attachments';
const data = {
"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"
]
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/file_attachments -d { }

Required Scope

file_attachments.write or all

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"
],
"created_at": "2020-06-24T01:27:32.045336+00:00"
}
}

Params

param description
patient_id
guid
ID of the patient profile onto which the file will be attached
worker_id
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
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

Retrieves file attachments, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the file attachments resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/file_attachments -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/file_attachments'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/file_attachments';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/file_attachments

Required Scope

file_attachments.read or all

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"
],
"created_at": "2020-06-24T01:27:32.045336+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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 of the file uploads record.
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'
headers = {'Content-Type': 'image/png'}
file_data = open('example.png', 'rb')
r = requests.post(url, data=file_data, headers=headers)

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

Required Scope

all

Params

param description
Content-Type
string
MIME type of the file being uploaded. Accepted MINE types: image/tiff, image/jpeg, image/png, application/pdf. Must be included as a header.
data
binary
The binary data of the file.

Get

Retrieves a single file upload by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/file_uploads/efbcc819-f25f-4bf4-afd4-198a035d5340 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/file_uploads/efbcc819-f25f-4bf4-afd4-198a035d5340'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/file_uploads/efbcc819-f25f-4bf4-afd4-198a035d5340';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/file_uploads/:id

Required Scope

file_uploads.read or all

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

Params

param description
id
guid
The primary identifier of the file uploads record.

Find

Retrieves file uploads, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the file uploads resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/file_uploads -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/file_uploads'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/file_uploads';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/file_uploads

Required Scope

file_uploads.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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 of the integration tasks record.
status
enum
Status of the task. Possible options are, unattempted, running, failed, or succeeded
patient_id
guid
The ID of the patient
ref_ids
array string
Array of external IDs associated with the tasks, linking the task to the resource in external systems.
job_id
string
Groups related tasks together
task_name
string
The name of the task prefixed by the name of the job
updated_at
isodatetime
Datetime the resource was last updated
created_at
isodatetime
Datetime the resource was created
errors
array integration-errors
Array of all the errors that resulted from this specific task. Note, these errors do not roll up to parent tasks.

Model integration-errors

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

Integration jobs

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

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

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

A custom integration job could be structured as follows:

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

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

Get

Retrieves a single integration task by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/integration_tasks/9bf1e295-47f5-4027-a382-008c860694c2 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/integration_tasks/9bf1e295-47f5-4027-a382-008c860694c2'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/integration_tasks/9bf1e295-47f5-4027-a382-008c860694c2';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/integration_tasks/:id

Required Scope

integration_tasks.read or all

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."
}
]
}
}

Params

param description
id
guid
The primary identifier of the integration tasks record.

Find

Finds integration tasks, using param filters.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/integration_tasks -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/integration_tasks'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/integration_tasks';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/integration_tasks

Required Scope

integration_tasks.read or all

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."
}
]
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
job_id
string
Groups related tasks together
task_name
string
The name of the task prefixed by the name of the job
ref_id
string
An external ID associated with the task, linking the task to the resource in external systems.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

A patient facing assessment link is a unique, one-time link that can be shared with a patient so they can fill out the assessment independently.

Generated links are only valid for the specific duration. This duration is set to 30 days by default, although it can be changed through a PSE request

Example Response

{
"url": "https://survey.welkinhealth.com/beta/?token=6db22d8e-de8e-43a8-be5c-19957dd2b2a0&spec_name=pet_wellness",
"created_at": "2020-05-28T14:19:29.503879+00:00",
"updated_at": "2020-05-28T14:19:29.503904+00:00",
"patient_id": "4f0a3adf-8e74-4981-a984-1dc079df577c",
"expire_time": "2020-06-27T14:19:29.500985+00:00",
"id": "6db22d8e-de8e-43a8-be5c-19957dd2b2a0"
}
param description
id
guid
The primary identifier of the patient facing assessment links record.
patient_id
guid
ID of the patient on which the assessment response will be placed
expire_time
Datetime when the link will expire
created_at
isodatetime
Datetime the resource was created
updated_at
isodatetime
Datetime the resource was last updated
url
Fully qualified URL to be presented to the user to fill out the assessment

Retrieves a single patient facing assessment link by id.

Example Request

curl -XGET https://api.welkinhealth.com/v1/patient_facing_assessment_links/6db22d8e-de8e-43a8-be5c-19957dd2b2a0 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/patient_facing_assessment_links/6db22d8e-de8e-43a8-be5c-19957dd2b2a0'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/patient_facing_assessment_links/6db22d8e-de8e-43a8-be5c-19957dd2b2a0';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/patient_facing_assessment_links/:id

patient_facing_assessment_links.read or all

Example Response

{
"data": {
"url": "https://survey.welkinhealth.com/beta/?token=6db22d8e-de8e-43a8-be5c-19957dd2b2a0&spec_name=pet_wellness",
"created_at": "2020-05-28T14:19:29.503879+00:00",
"updated_at": "2020-05-28T14:19:29.503904+00:00",
"patient_id": "4f0a3adf-8e74-4981-a984-1dc079df577c",
"expire_time": "2020-06-27T14:19:29.500985+00:00",
"id": "6db22d8e-de8e-43a8-be5c-19957dd2b2a0"
}
}
param description
id
guid
The primary identifier of the patient facing assessment links record.

Creates a new patient facing assessment link.

Example Request

curl -XPOST https://api.welkinhealth.com/v1/patient_facing_assessment_links -d '{
"patient_id": "4f0a3adf-8e74-4981-a984-1dc079df577c",
"spec_name": "some_string"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"patient_id": "4f0a3adf-8e74-4981-a984-1dc079df577c",
"spec_name": "some_string"
}
url = 'https://api.welkinhealth.com/v1/patient_facing_assessment_links'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/patient_facing_assessment_links';
const data = {
"patient_id": "4f0a3adf-8e74-4981-a984-1dc079df577c",
"spec_name": "some_string"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/patient_facing_assessment_links -d { }

patient_facing_assessment_links.write or all

Example Response

{
"data": {
"url": "https://survey.welkinhealth.com/beta/?token=6db22d8e-de8e-43a8-be5c-19957dd2b2a0&spec_name=pet_wellness",
"created_at": "2020-05-28T14:19:29.503879+00:00",
"updated_at": "2020-05-28T14:19:29.503904+00:00",
"patient_id": "4f0a3adf-8e74-4981-a984-1dc079df577c",
"expire_time": "2020-06-27T14:19:29.500985+00:00",
"id": "6db22d8e-de8e-43a8-be5c-19957dd2b2a0"
}
}
param description
patient_id
guid
ID of the patient on which the assessment response will be placed
spec_name
string
The ref_name for the assessment as it appears in Workshop.

Retrieves patient facing assessment links, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the patient facing assessment links resource.

Example Request

curl -XGET https://api.welkinhealth.com/v1/patient_facing_assessment_links -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/patient_facing_assessment_links'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/patient_facing_assessment_links';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/patient_facing_assessment_links

patient_facing_assessment_links.read or all

Example Response

{
"data": [
{
"url": "https://survey.welkinhealth.com/beta/?token=6db22d8e-de8e-43a8-be5c-19957dd2b2a0&spec_name=pet_wellness",
"created_at": "2020-05-28T14:19:29.503879+00:00",
"updated_at": "2020-05-28T14:19:29.503904+00:00",
"patient_id": "4f0a3adf-8e74-4981-a984-1dc079df577c",
"expire_time": "2020-06-27T14:19:29.500985+00:00",
"id": "6db22d8e-de8e-43a8-be5c-19957dd2b2a0"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}
param description
patient_id
guid
ID of the patient on which the assessment response will be placed
spec_name
string
The ref_name for the assessment as it appears in Workshop.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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.

english, spanish, vietnamese, tagalog, chinese, arabic, korean, punjabi, russian, other, unknown, cantonese, hmong, mandarin_chinese, abkhazian, afar, afrikaans, akan, albanian, amharic, aragonese, armenian, assamese, avaric, avestan, aymara, azerbaijani, bambara, bashkir, basque, belarusian, bengali, bihari, bislama, bosnian, breton, bulgarian, burmese, catalan, chamorro, chechen, chewa, chuvash, cornish, corsican, cree, croatian, czech, danish, maldivian, dutch, dzongkha, esperanto, estonian, ewe, faroese, fijian, finnish, french, fulah, galician, georgian, german, greek, guarani, gujarati, haitian, hausa, hebrew, herero, hindi, hiri_motu, hungarian, indonesian, irish, igbo, inupiaq, ido, icelandic, italian, inuktitut, japanese, javanese, greenlandic, kannada, kanuri, kashmiri, kazakh, central_khmer, kikuyu, kinyarwanda, kyrgyz, komi, kongo, kurdish, kwanyama, latin, luxembourgish, ganda, limburgish, lingala, lao, lithuanian, luba_katanga, latvian, manx, macedonian, malagasy, malay, malayalam, maltese, maori, marathi, marshallese, mongolian, nauru, navajo, north_ndebele, nepali, ndonga, norwegian_bokmal, norwegian_nynorsk, norwegian, nuosu, south_ndebele, occitan, ojibwa, oromo, oriya, ossetian, pali, persian, polish, pashto, portuguese, quechua, romansh, rundi, romanian, sanskrit, sardinian, sindhi, northern_sami, samoan, sango, serbian, gaelic, shona, sinhalese, slovak, slovenian, somali, southern_sotho, sundanese, swahili, swati, swedish, tamil, telugu, tajik, thai, tigrinya, tibetan, turkmen, tswana, tonga, turkish, tsonga, tatar, twi, tahitian, uyghur, ukrainian, urdu, uzbek, venda, volapuk, walloon, welsh, wolof, western_frisian, xhosa, yiddish, yoruba, chuang, zului

Model

Example Response

{
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phase": "intake",
"primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054",
"provider_id_number": "7IHnPI80",
"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",
"is_active": "true",
"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 of the patients record.
phase
enum
The phase (or stage) of care that this patient is in. The possible set of phases is defined in Workshop.
is_active
boolean
true or false for whether the patient record is active or inactive. Caution: marking a patient inactive will also finish calendar events and dismiss alerts.
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
optional date
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
optional zip_code
Zip code of this patient's address in five or nine digit form. 94115 or 94115-4619
state
optional state
Two character abbreviation of the state in which this patient resides
country
country
Country in which this patient lives
primary_language
optional enum
This patient's primary language. Available options include ISO 639-1:
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.
provider_id_number
string
ID of the patient in 3rd party system. Can be any string format.

Get

Retrieves a single patient by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/patients/45ceeba9-4944-43d1-b34d-0c36846acd4c -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/patients/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/patients/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/patients/:id

Required Scope

patients.read or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phase": "intake",
"primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054",
"provider_id_number": "7IHnPI80",
"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",
"is_active": "true",
"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 of the patients record.

Create

Creates a new patient.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/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",
"provider_id_number": "7IHnPI80"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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",
"provider_id_number": "7IHnPI80"
}
url = 'https://api.welkinhealth.com/v1/patients'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/patients';
const data = {
"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",
"provider_id_number": "7IHnPI80"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/patients -d { }

Required Scope

patients.write or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phase": "intake",
"primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054",
"provider_id_number": "7IHnPI80",
"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",
"is_active": "true",
"updated_at": "2018-09-12T01:27:32.108773+00:00",
"created_at": "2018-09-12T01:27:32.109872+00:00"
}
}

Params

param description
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
date
Date of birth of this patient
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 or nine digit form. 94115 or 94115-4619
state
state
Two character abbreviation of the state in which this patient resides
country
country
Country in which this patient lives
primary_language
enum
This patient's primary language. Available options include ISO 639-1:
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.
provider_id_number
string
ID of the patient in 3rd party system. Can be any string format.
email
email
(Deprecated) Email addresses should be created via the email address endpoint.
phone
e164_phone
(Deprecated) Phone numbers should be created via the phone number endpoint.

Update

Updates an existing patient.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/v1/patients/45ceeba9-4944-43d1-b34d-0c36846acd4c -d '{
"phase": "intake",
"is_active": "true",
"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",
"provider_id_number": "7IHnPI80"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"phase": "intake",
"is_active": "true",
"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",
"provider_id_number": "7IHnPI80"
}
url = 'https://api.welkinhealth.com/v1/patients/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/patients/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const data = {
"phase": "intake",
"is_active": "true",
"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",
"provider_id_number": "7IHnPI80"
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

patients.write or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phase": "intake",
"primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054",
"provider_id_number": "7IHnPI80",
"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",
"is_active": "true",
"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 of the patients record.
phase
enum
The phase (or stage) of care that this patient is in. The possible set of phases is defined in Workshop.
is_active
boolean
true or false for whether the patient record is active or inactive. Caution: marking a patient inactive will also finish calendar events and dismiss alerts.
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
date
Date of birth of this patient
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 or nine digit form. 94115 or 94115-4619
state
state
Two character abbreviation of the state in which this patient resides
country
country
Country in which this patient lives
primary_language
enum
This patient's primary language. Available options include ISO 639-1:
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.
provider_id_number
string
ID of the patient in 3rd party system. Can be any string format.

Find

Retrieves patients, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the patients resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/patients -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/patients'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/patients';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/patients

Required Scope

patients.read or all

Example Response

{
"data": [
{
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phase": "intake",
"primary_worker_id": "1ecacc1f-1a4c-4bcb-9790-528642cba054",
"provider_id_number": "7IHnPI80",
"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",
"is_active": "true",
"updated_at": "2018-09-12T01:27:32.108773+00:00",
"created_at": "2018-09-12T01:27:32.109872+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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 its 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 of the phone numbers record.
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 identity 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 by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/phone_numbers/:id

Required Scope

phone_numbers.read or all

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

Params

param description
id
guid
The primary identifier of the phone numbers record.

Create

Creates a new phone number.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/phone_numbers -d '{
"patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"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
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"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
}
url = 'https://api.welkinhealth.com/v1/phone_numbers'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/phone_numbers';
const data = {
"patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"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
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/phone_numbers -d { }

Required Scope

phone_numbers.write or all

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

Params

param description
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 identity 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

Update

Updates an existing phone number.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/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
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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
}
url = 'https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f';
const data = {
"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
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

phone_numbers.write or all

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

Params

param description
id
guid
The primary identifier of the phone numbers record.
phone_number
e164_phone
Not allowed. To update a patient's phone number you must delete the phone number and create a new phone number. This will also remove the existing conversation associated with this phone number.
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 identity 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

Delete

Deletes a single phone number.

Invocation

Example Request

curl -XDELETE https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f'
resp = requests.delete(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f';
const response = await axios({method: 'delete', url: url, headers: headers});

DELETE /v1/phone_numbers/:id

Required Scope

phone_numbers.write or all

Example Response

{
"data": null
}

Params

param description
id
guid
The primary identifier of the phone numbers record.

Find

Retrieves phone numbers, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the phone numbers resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/phone_numbers -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/phone_numbers'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/phone_numbers';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/phone_numbers

Required Scope

phone_numbers.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
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.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Find By Post

Retrieves phone numbers, filtered by the supplied parameters, sent in the POST body. Only the parameters listed below are supported in Find By Post for the phone numbers resource.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/phone_numbers/find -d '{
"patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phone_number": "+15555555555"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/phone_numbers/find'
data = {
"patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phone_number": "+15555555555"
}
resp = requests.post(url,headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/phone_numbers/find';
const data = {
"patient_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"user_id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"phone_number": "+15555555555"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/phone_numbers/find

Required Scope

phone_numbers.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
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
string
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.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Profile Phone Numbers

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

Each profile phone number has its 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 profile.

Model

Example Response

{
"id": "c9a72425-f433-4c6c-9d95-4057b25acc2f",
"profile_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"phone_number": "+15555555555",
"phone_number_type": "landline",
"friendly_name": "main number",
"verified": false,
"archived": 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 of the profile phone numbers record.
profile_id
guid
The identifier of the profile to which this phone number is associated.
phone_number
e164_phone
The phone number to be associated with the profile. Must be in international, E.164 format.
phone_number_type
enum
(cell, landline, other)
friendly_name
string
Name of the phone number to help the worker differentiate between profile phone numbers
verified
boolean
true only if you have confirmed this phone number is owned by the profile by calling this number and confirming the profile's identity details. Default false
archived
boolean
true if the phone number has been removed from the Profile.
opted_in_to_sms
boolean
true only if the profile 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 profile 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 profile has consented verbally, digitally, or in writing to receiving voicemail at this number. Default false
opted_in_to_phone
boolean
true only if the profile has consented verbally, digitally, or in writing to receiving calls at this number. Default false
automatic_recipient
boolean
true only if the profile 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 profile phone number by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/profile_phone_numbers/:id

Required Scope

profile_phone_numbers.read or all

Example Response

{
"data": {
"id": "c9a72425-f433-4c6c-9d95-4057b25acc2f",
"profile_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"phone_number": "+15555555555",
"phone_number_type": "landline",
"friendly_name": "main number",
"verified": false,
"archived": 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 of the profile phone numbers record.

Create

Creates a new profile phone number.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/profile_phone_numbers -d '{
"profile_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
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"profile_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
}
url = 'https://api.welkinhealth.com/v1/profile_phone_numbers'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/profile_phone_numbers';
const data = {
"profile_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
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/profile_phone_numbers -d { }

Required Scope

profile_phone_numbers.write or all

Example Response

{
"data": {
"id": "c9a72425-f433-4c6c-9d95-4057b25acc2f",
"profile_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"phone_number": "+15555555555",
"phone_number_type": "landline",
"friendly_name": "main number",
"verified": false,
"archived": 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
profile_id
guid
The identifier of the profile to which this phone number is associated.
phone_number
e164_phone
The phone number to be associated with the profile. Must be in international, E.164 format.
phone_number_type
enum
(cell, landline, other)
friendly_name
string
Name of the phone number to help the worker differentiate between profile phone numbers
verified
boolean
true only if you have confirmed this phone number is owned by the profile by calling this number and confirming the profile's identity details. Default false
opted_in_to_sms
boolean
true only if the profile 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 profile 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 profile has consented verbally, digitally, or in writing to receiving voicemail at this number. Default false
opted_in_to_phone
boolean
true only if the profile has consented verbally, digitally, or in writing to receiving calls at this number. Default false
automatic_recipient
boolean
true only if the profile has consented verbally, digitally, or in writing to receiving automated SMS messages at this number. Default false

Update

Updates an existing profile phone number.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/v1/profile_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
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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
}
url = 'https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f';
const data = {
"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
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

profile_phone_numbers.write or all

Example Response

{
"data": {
"id": "c9a72425-f433-4c6c-9d95-4057b25acc2f",
"profile_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"phone_number": "+15555555555",
"phone_number_type": "landline",
"friendly_name": "main number",
"verified": false,
"archived": 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 of the profile phone numbers record.
phone_number
e164_phone
The phone number to be associated with the profile. Must be in international, E.164 format.
phone_number_type
enum
(cell, landline, other)
friendly_name
string
Name of the phone number to help the worker differentiate between profile phone numbers
verified
boolean
true only if you have confirmed this phone number is owned by the profile by calling this number and confirming the profile's identity details. Default false
opted_in_to_sms
boolean
true only if the profile 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 profile 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 profile has consented verbally, digitally, or in writing to receiving voicemail at this number. Default false
opted_in_to_phone
boolean
true only if the profile has consented verbally, digitally, or in writing to receiving calls at this number. Default false
automatic_recipient
boolean
true only if the profile has consented verbally, digitally, or in writing to receiving automated SMS messages at this number. Default false

Delete

Deletes a single profile phone number.

Invocation

Example Request

curl -XDELETE https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f'
resp = requests.delete(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/profile_phone_numbers/c9a72425-f433-4c6c-9d95-4057b25acc2f';
const response = await axios({method: 'delete', url: url, headers: headers});

DELETE /v1/profile_phone_numbers/:id

Required Scope

profile_phone_numbers.write or all

Example Response

{
"data": null
}

Params

param description
id
guid
The primary identifier of the profile phone numbers record.

Find

Retrieves profile phone numbers, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the profile phone numbers resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/profile_phone_numbers -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/profile_phone_numbers'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/profile_phone_numbers';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/profile_phone_numbers

Required Scope

profile_phone_numbers.read or all

Example Response

{
"data": [
{
"id": "c9a72425-f433-4c6c-9d95-4057b25acc2f",
"profile_id": "9a75cd83-7247-4d6b-a1dd-00e1aca2219f",
"phone_number": "+15555555555",
"phone_number_type": "landline",
"friendly_name": "main number",
"verified": false,
"archived": 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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
profile_id
guid
The identifier of the profile to which this phone number is associated.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Profiles

Profiles represent non-patient entities in Welkin. These could be family members, loved ones, care givers, doctors, clinic locations, regions, patient cohorts, and many more. Relationships link Profiles to Patients, Workers, and other Profiles.

In Workshop you can define the set of fields on each Profile type. You can also define the Relationships which link them.

Model

Example Response

{
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
},
"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 of the profiles record.
profile_type_name
string
Name of the Profile spec as defined in Workshop
body
json
A JSON object representing the fields that are required for that Profile type
updated_at
isodatetime
Datetime the resource was last updated
created_at
isodatetime
Datetime the resource was created

Get

Retrieves a single profile by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/profiles/45ceeba9-4944-43d1-b34d-0c36846acd4c -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/profiles/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/profiles/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/profiles/:id

Required Scope

profiles.read or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
},
"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 of the profiles record.

Create

Creates a new profile.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/profiles -d '{
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
}
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
}
}
url = 'https://api.welkinhealth.com/v1/profiles'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/profiles';
const data = {
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
}
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/profiles -d { }

Required Scope

profiles.write or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
},
"updated_at": "2018-09-12T01:27:32.108773+00:00",
"created_at": "2018-09-12T01:27:32.109872+00:00"
}
}

Params

param description
profile_type_name
string
Name of the Profile spec as defined in Workshop
body
json
A JSON object representing the fields that are required for that Profile type

Update

Updates an existing profile.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/v1/profiles/45ceeba9-4944-43d1-b34d-0c36846acd4c -d '{
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
}
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
}
}
url = 'https://api.welkinhealth.com/v1/profiles/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/profiles/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const data = {
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
}
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

profiles.write or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
},
"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 of the profiles record.
body
json
A JSON object representing the fields that are required for that Profile type

Find

Retrieves profiles, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the profiles resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/profiles -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/profiles'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/profiles';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/profiles

Required Scope

profiles.read or all

Example Response

{
"data": [
{
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"profile_type_name": "test_profile",
"body": {
"first_name": "Grace",
"last_name": "Hopper",
"birthday": "1906-12-09",
"gender": "Female"
},
"updated_at": "2018-09-12T01:27:32.108773+00:00",
"created_at": "2018-09-12T01:27:32.109872+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
profile_type_name
string
Name of the Profile spec as defined in Workshop
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
integer
Maximum number of items to include in the response

Relationship Records

Relationships link patients, worker, and profiles together allowing workers to visualize the care network of a patient. Relationships also allow workers to quickly navigate to view details about the people and places in a patient's care network.

Model

Example Response

{
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"relationship_type_id": "family_member",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"archived_at": null,
"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 of the relationship records record.
created_at
isodatetime
Datetime the resource was created
updated_at
isodatetime
Datetime the resource was last updated
start_date
date
The date on which the relationship began between entity 1 and entity 2. This date must be in the past relative to current time.
end_date
date
The date on which the relationship ended between entity 1 and entity 2. This date must be in the past relative to current time and must be after start_date.
archived_at
isodatetime
The date when the relationship was archived (hidden from workers in Welkin).
entity_1_id
guid
The ID of the entity (patient, worker, or profile) filling the role of entity 1 as defined in Workshop.
entity_2_id
guid
The ID of the entity (patient, worker, or profile) filling the role of entity 2 as defined in Workshop.
relationship_type_id
string
The ID of the relationship type as defined in Workshop. This relationship type defines the roles that entity 1 and entity 2 fulfill in the relationship.

Get

Retrieves a single relationship record by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/relationship_records/:id

Required Scope

relationship_records.read or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"relationship_type_id": "family_member",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"archived_at": null,
"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 of the relationship records record.

Create

Creates a new relationship record.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/relationship_records -d '{
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"relationship_type_id": "family_member"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"relationship_type_id": "family_member"
}
url = 'https://api.welkinhealth.com/v1/relationship_records'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/relationship_records';
const data = {
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"relationship_type_id": "family_member"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/relationship_records -d { }

Required Scope

relationship_records.write or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"relationship_type_id": "family_member",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"archived_at": null,
"updated_at": "2018-09-12T01:27:32.108773+00:00",
"created_at": "2018-09-12T01:27:32.109872+00:00"
}
}

Params

param description
start_date
date
The date on which the relationship began between entity 1 and entity 2. This date must be in the past relative to current time.
end_date
date
The date on which the relationship ended between entity 1 and entity 2. This date must be in the past relative to current time and must be after start_date.
entity_1_id
guid
The ID of the entity (patient, worker, or profile) filling the role of entity 1 as defined in Workshop.
entity_2_id
guid
The ID of the entity (patient, worker, or profile) filling the role of entity 2 as defined in Workshop.
relationship_type_id
string
The ID of the relationship type as defined in Workshop. This relationship type defines the roles that entity 1 and entity 2 fulfill in the relationship.

Update

Updates an existing relationship record.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c -d '{
"start_date": "2018-02-02",
"end_date": "2018-12-17"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"start_date": "2018-02-02",
"end_date": "2018-12-17"
}
url = 'https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const data = {
"start_date": "2018-02-02",
"end_date": "2018-12-17"
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

relationship_records.write or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"relationship_type_id": "family_member",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"archived_at": null,
"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 of the relationship records record.
start_date
date
The date on which the relationship began between entity 1 and entity 2. This date must be in the past relative to current time.
end_date
date
The date on which the relationship ended between entity 1 and entity 2. This date must be in the past relative to current time and must be after start_date.

Delete

Archive a specific relationship. Archived relationships no longer show up in the coach portal but do still exist in the data.

Invocation

Example Request

curl -XDELETE https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c'
resp = requests.delete(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/relationship_records/45ceeba9-4944-43d1-b34d-0c36846acd4c';
const response = await axios({method: 'delete', url: url, headers: headers});

DELETE /v1/relationship_records/:id

Required Scope

relationship_records.write or all

Example Response

{
"data": {
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"relationship_type_id": "family_member",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"archived_at": null,
"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 of the relationship records record.

Find

Retrieves relationship records, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the relationship records resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/relationship_records -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/relationship_records'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/relationship_records';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/relationship_records

Required Scope

relationship_records.read or all

Example Response

{
"data": [
{
"id": "45ceeba9-4944-43d1-b34d-0c36846acd4c",
"relationship_type_id": "family_member",
"entity_1_id": "35ceeba9-5944-46d1-e34d-1c36846eee3b",
"entity_2_id": "12cedba8-4344-22d2-e14d-2c23666edc12",
"start_date": "2018-02-02",
"end_date": "2018-12-17",
"archived_at": null,
"updated_at": "2018-09-12T01:27:32.108773+00:00",
"created_at": "2018-09-12T01:27:32.109872+00:00"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

param description
relationship_type_id
string
The ID of the relationship type as defined in Workshop. This relationship type defines the roles that entity 1 and entity 2 fulfill in the relationship.
entity_id
guid
The ID of an entity to find relationships for. This entity can fulfill entity 1 or entity 2 in the relationship.
page[from]
isodatetime
The earliest timestamp to include in the response
page[to]
isodatetime
The latest timestamp to include in the response
page[size]
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 of the sms messages record.
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 message 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 by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/sms_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26 -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/sms_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/sms_messages/0adfd8b0-3497-48fc-8ffa-eb2add2cde26';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/sms_messages/:id

Required Scope

sms_messages.read or all

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

Params

param description
id
guid
The primary identifier of the sms messages record.

Create

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

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/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"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"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"
}
url = 'https://api.welkinhealth.com/v1/sms_messages'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/sms_messages';
const data = {
"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"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/sms_messages -d { }

Required Scope

sms_messages.write or all

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

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 message 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
welkin_send
boolean
Indicates if Welkin should send the message for outbound SMS messages

Find

Retrieves sms messages, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the sms messages resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/sms_messages -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/sms_messages'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/sms_messages';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/sms_messages

Required Scope

sms_messages.read or all

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"
}
],
"links": "Elided for simplicity, see Find Endpoints Overview above"
}

Params

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

Unavailable Times

Unavailable Times represent time when events can not be scheduled for the worker. These blocks are either single blocks are repeating blocks of time. Unavailable times are linked to a worker's Calendar.

Model

Example Response

{
"id": "7bbe0d77-9deb-4e81-8aff-6fb5d112e85f",
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly",
"calendar_id": "4d9a06b3-4568-488e-820c-217f628b0ea4",
"updated_at": "2019-03-01T12:10:11.10+00:00",
"created_at": "2019-03-01T12:10:11.10+00:00"
}
param description
id
guid
The primary identifier of the unavailable times record.
date
date
The initial date of this unavailability, in the format YYYY-MM-DD in the worker's local timezone.
all_day
boolean
true if this unavailability will last the whole day
start_time
string
The start time of a worker's unavailability in their local timezone. Uses 24-hour time notation
end_time
string
The ending time of a worker's unavailability (inclusive) in their local timezone. Uses 24-hour time notation
recurrence
enum
The frequency at which this block of unavailable time repeats. If specified, this unavailable time block will repeat at this interval until the unavailable time block is deleted. Possible values none, daily, or weekly
calendar_id
guid
The ID of the calendar this day belongs to
updated_at
isodatetime
Datetime the resource was created (excluding updates to events on the associated calendar)
created_at
isodatetime
Datetime the resource was created

Get

Retrieves a single unavailable time by id.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"}
const url = 'https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/unavailable_times/:id

Required Scope

unavailable_times.read or all

Example Response

{
"data": {
"id": "7bbe0d77-9deb-4e81-8aff-6fb5d112e85f",
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly",
"calendar_id": "4d9a06b3-4568-488e-820c-217f628b0ea4",
"updated_at": "2019-03-01T12:10:11.10+00:00",
"created_at": "2019-03-01T12:10:11.10+00:00"
}
}

Params

param description
id
guid
The primary identifier of the unavailable times record.

Create

Creates a new unavailable time.

Invocation

Example Request

curl -XPOST https://api.welkinhealth.com/v1/unavailable_times -d '{
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly",
"calendar_id": "4d9a06b3-4568-488e-820c-217f628b0ea4"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly",
"calendar_id": "4d9a06b3-4568-488e-820c-217f628b0ea4"
}
url = 'https://api.welkinhealth.com/v1/unavailable_times'
resp = requests.post(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/unavailable_times';
const data = {
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly",
"calendar_id": "4d9a06b3-4568-488e-820c-217f628b0ea4"
};
const response = await axios({method: 'post', url: url, headers: headers, data: data});

POST /v1/unavailable_times -d { }

Required Scope

unavailable_times.write or all

Example Response

{
"data": {
"id": "7bbe0d77-9deb-4e81-8aff-6fb5d112e85f",
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly",
"calendar_id": "4d9a06b3-4568-488e-820c-217f628b0ea4",
"updated_at": "2019-03-01T12:10:11.10+00:00",
"created_at": "2019-03-01T12:10:11.10+00:00"
}
}

Params

param description
date
date
The initial date of this unavailability, in the format YYYY-MM-DD in the worker's local timezone.
all_day
boolean
true if this unavailability will last the whole day
start_time
string
The start time of a worker's unavailability in their local timezone. Uses 24-hour time notation
end_time
string
The ending time of a worker's unavailability (inclusive) in their local timezone. Uses 24-hour time notation
recurrence
enum
The frequency at which this block of unavailable time repeats. If specified, this unavailable time block will repeat at this interval until the unavailable time block is deleted. Possible values none, daily, or weekly
calendar_id
guid
The ID of the calendar this day belongs to

Update

Updates an existing unavailable time.

Invocation

Example Request

curl -XPUT https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f -d '{
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly"
}' -H "Authorization: Bearer <your access token>" -H "Content-Type: application/json"
import requests
headers = {"Authorization": "Bearer <token>"}
data = {
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly"
}
url = 'https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f'
resp = requests.put(url, headers=headers, json=data).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f';
const data = {
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly"
};
const response = await axios({method: 'put', url: url, headers: headers, data: data});

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

Required Scope

unavailable_times.write or all

Example Response

{
"data": {
"id": "7bbe0d77-9deb-4e81-8aff-6fb5d112e85f",
"date": "2019-01-02",
"all_day": false,
"start_time": "12:00:00",
"end_time": "14:30:00",
"recurrence": "weekly",
"calendar_id": "4d9a06b3-4568-488e-820c-217f628b0ea4",
"updated_at": "2019-03-01T12:10:11.10+00:00",
"created_at": "2019-03-01T12:10:11.10+00:00"
}
}

Params

param description
id
guid
The primary identifier of the unavailable times record.
date
date
The initial date of this unavailability, in the format YYYY-MM-DD in the worker's local timezone.
all_day
boolean
true if this unavailability will last the whole day
start_time
string
The start time of a worker's unavailability in their local timezone. Uses 24-hour time notation
end_time
string
The ending time of a worker's unavailability (inclusive) in their local timezone. Uses 24-hour time notation
recurrence
enum
The frequency at which this block of unavailable time repeats. If specified, this unavailable time block will repeat at this interval until the unavailable time block is deleted. Possible values none, daily, or weekly

Delete

Deletes a single unavailable time.

Invocation

Example Request

curl -XDELETE https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f'
resp = requests.delete(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/unavailable_times/7bbe0d77-9deb-4e81-8aff-6fb5d112e85f';
const response = await axios({method: 'delete', url: url, headers: headers});

DELETE /v1/unavailable_times/:id

Required Scope

unavailable_times.write or all

Example Response

{
"data": null
}

Params

param description
id
guid
The primary identifier of the unavailable times record.

Find

Retrieves unavailable times, filtered by the supplied parameters. Only the parameters listed below are supported in Find for the unavailable times resource.

Invocation

Example Request

curl -XGET https://api.welkinhealth.com/v1/unavailable_times -H "Authorization: Bearer <your access token>"
import requests
headers = {"Authorization": "Bearer <token>"}
url = 'https://api.welkinhealth.com/v1/unavailable_times'
resp = requests.get(url, headers=headers).json()
const axios = require('axios');
const headers = {"Authorization": "Bearer <token>"};
const url = 'https://api.welkinhealth.com/v1/unavailable_times';
const response = await axios({method: 'get', url: url, headers: headers});

GET /v1/unavailable_times

Required Scope

unavailable_times.read or all

Example Response

{
"data": [
{
"id": "7bbe0d77-9deb-4e81-8aff-6fb5d112e85f",
"date": "2019-01-02",
"all_day": false,
"start_time":