Workpath Housecall API

The path connecting healthcare companies to in-home healthcare.

Getting Started

This document outlines the behaviors expected from Intake API Version 2 (V2). The Workpath REST API provides programmatic access to Workpath data for use in client applications and partner integrations. This is a working document as we continue to update our API.

For general information visit this link: Workpath Intake API Overview

Information We Need

To start the appointment process, we require a certain amount of information from you about your patient, the provider of your patient, what labs you are wanting to run, and insurance information (if applicable). See the sections below about our endpoints you will need in order to create a full appointment.

Access to our Client Management Dashboard can be found here.

Need additional assistance? Click Here

"Hello World" API Use Example

In true developer fashion, we have provided a quick "Hello World" tutorial for you to try out! This example below will explain how to authenticate and then create a simple intake using our system.

The steps we will walk through:

  1. Create Your First API Key
  2. Retrieve A Token With Your API Key
  3. Create an Intake
  4. Fetch the Intake

1. Create Your First API Key

Workpath should provide you with a login email and password that has the correct user permissions needed to reach the /clients area. Once you have obtained those, you can start the process of working with our API! You will need to go here to login: Client Management.

Once you login using the email and password provided for you from Workpath, you will be directed to a screen that shows a button to "Add New Credential".

The image to the right shows an example Client Credential being created. Please note you need to check which permissions you want available to you. (You will be able to edit permissions later.)

Create a new API client

After you have saved your newly created client credential, you will be directed to a screen that looks like the image to the right. You now have two tabs at the top as well as two different buttons at the bottom. This is the credential edit screen where you can update permissions by checking or un-checking the permission boxes, revoke the client, and create API keys.

After saving a new client

To generate a new API key, click on the "API Keys" tab and then click the button that says "Add API Key".

The image to the right shows a newly generated API Key and Password pair. This is what you will need when you are communicating with our API. As the message on the image states, once you navigate away from that page, you will no longer be able to see the password, so make sure that you make a note of it in your records.

Create a new API key

Congratulations! You have created your first client credential and your first API key and password pairing!

Your screen will look similar to the image on the right. Once you have made your first client credential and API key and password pair, you will be able to create a second API key and password using our API. The instructions for that process are located HERE in the docs.

Client home screen

Need additional assistance? Click Here


2. Retrieve A Token With Your API Key

For this step, you will need the API key and password pair that you created in the previous step.

Before you make any calls to our API, you will need to use your API key to generate an access token. The details for creating this access token are located HERE in these docs.

Essentially, you will be sending a URL-encoded string to the /oauth/token route given and you will receive a JSON object back that includes your access token.

Need additional assistance? Click Here


3. Create an Intake

Using the access token that you requested in step two, you will then be able to create what we can an Intake! An intake will, in turn, create an appointment once the patient has filled out all of the required fields and submitted their response.

The Create Intake details, such as request attributes and response JSON objects, are located HERE in these docs.

Need additional assistance? Click Here


4. Fetch the Intake

Using the access token that you requested in step two, you can call GET https://api.workpath.co/intakes/[id] using the id of the intake you created in the previous step to fetch that particular intake.

Refer to the Intake Object details for the shape of the Intake JSON Object that will be returned to you HERE in these docs.

Need additional assistance? Click Here

Authentication and Keys

User resources provide authentication and config settings for individual users.


Authorization Code

The authorization code grant type is initiated from your client application. A URL will be constructed with specific parameters and navigated to, where the user will then sign in to Workpath. After a successful sign in, the user will authorize your application to access their information and then be redirected back to your client. The redirection URL will include a code that can be exchanged for an access token.

Authorization Code Initiation

This step will be initiated by your application. Your application will generate and store the required attributes which it can later reference when the request is sent back to your redirect URI. It will need to generate two random strings, one for the state and one for the code_verifier. Workpath will send the state back with the code to your redirect URI, so make sure your application saves the code verifier that can be referenced by the state later on.

Request Attributes

GET https://api.workpath.co/oauth/authorize

client_id string

required

API Credential key associated with client generated here.

redirect_uri string

required

Redirect URL associated with client generated here.

state string

required

Randomly generated string.

code_challenge string

required

SHA-256 and base64 encoded version of the code verifier.

code_challenge_method string

required

Always use S256.

response_type string

required

Always use code.
Example Request JSON
                    
  {
    "client_id": "3680ba42-822d-44db-8a5c-9d5ce35b639e",
    "redirect_uri": "https://url.com",
    "state": "iOTxFAXD7dYdsKhR9hGa",
    "code_challenge": "ZDU3N2VhZjJiYjRiY2QzZTg3M2NhNmVhZDUzYTQ4Nj...",
    "code_challenge_method": "S256",
    "response_type": "code",
    "onboarding": "1"
  }
                    
                  

Token Exchange

Authorization Code Grant Type

This step will take place once the request is sent back to your redirect URI. Two parameters will be available as query parameters, code and state. Use the state parameter to access the correct code verifier which will be used in the code exchanged request, as outlined in the attributes section of these instructions.

Alternatively, if anything went wrong during authorization, an error_type and error_description will be sent as query params to allow your application to show the error accordingly.

Request Attributes

POST https://api.workpath.co/oauth/token

grant_type string

required

OAuth grant type. Value should be authorization_code.

code string

required

Code sent back as query param in redirect URI.

code_verifier string

required

String referenced by state sent back as query param in redirect URI.

code_challenge_method string

required

Always use S256.

client_id string

required

API Credential key associated with client generated here.

redirect_uri string

required

Redirect URL associated with client generated here.
Example Request JSON
                    
  {
    "grant_type": "authorization_code",
    "code": "blIbZ1d~3j@7W*N2prkc",
    "code_verifier": "IotXfaxd7DyDSkHr9HgA",
    "code_challenge_method": "S256",
    "client_id": "3680ba42-822d-44db-8a5c-9d5ce35b639e",
    "redirect_uri": "https://url.com"
  }
                    
                  
Response Attributes

access_token string

Token value.

expires_in string

Seconds to expiration of the token.

access_token_expires_at string

Expiration time stamp.

scope string

Space-separated list of scopes.

token_type string

Token type.
Example Response JSON
                    
  {
    "access_token": "035736ac-abb5-49b9-a08d-c83d09398ba1",
    "expires_in": 1800,
    "access_token_expires_at": "2016-12-04T16:05:49.401Z",
    "scope": "",
    "token_type": "Bearer"
  }                  
                    
                  

Client Credential Grant Type

Issue a new access token. Requests can include an HTTP Basic authorization header representing a valid API key and password or client_id and client_secret as attributes in the request body.

Basic Auth Example: Authorization: Basic [value], where the value is the base-64 encoded representation of '[api-key]:[api-password]'.

The access token returned by this method is used as the bearer token for all subsequent requests to the API in the form of an auth header (Authorization: Bearer [access token]). Subsequent requests made using an expired or invalid token will return a 401 - Unauthorized response code.

Note: the content encoding for this endpoint is 'application/x-www-form-urlencoded', unlike the 'application/json' used by all other API methods.

Request Parameters

POST https://api.workpath.co/oauth/token

grant_type string

required

OAuth grant type. Value should be client_credentials.

client_id string

API Key provided by Workpath. Not needed with BasicAuth.

client_secret string

API Password provided by Workpath. Not needed with BasicAuth.
Example URL-Encoded String

grant_type=client_credentials&client_id=4ab41347-e24f-475d-b1da-bce37ae31af3&client_secret=SX0LGy6z!Pa~%2CV-!A%3Aaz

Response Attributes

access_token string

Token value.

expires_in string

Seconds to expiration of the token.

access_token_expires_at string

Expiration time stamp.

scope string

Space-separated list of scopes.

token_type string

Token type.
Example Response JSON
                    
  {
    "access_token": "035736ac-abb5-49b9-a08d-c83d09398ba1",
    "expires_in": 1800,
    "access_token_expires_at": "2016-12-04T16:05:49.401Z",
    "scope": "",
    "token_type": "Bearer"
  }                  
                    
                  

Need additional assistance? Click Here

Credential Management (API Credentials)

All API credential requests require a BasicAuth header by using a previously created API credential. The provided BasicAuth header will then be used to determine if the request is allowed based on the API credential being accessed, only API credentials with the same associated client will work with each other. For API credential creation, the associated BasicAuth credential provided in the request will be used to create another API credential associated with the same client. Cross-client access is not allowed and will result in an unauthorized response.


Create API Credentials

POST https://api.workpath.co/api-keys

Adds a new API Credential (limit 2 for each client).

Creating your first API Credential is done through the UI here. Calling this endpoint creates a second API Credential based on the first one you created. You may only have two credentials at a time. Attempting to create a third will result in a thrown error.

Response Attributes

id number

API Key ID.

key string

API Key.

client_id string

Associated client ID.

is_active boolean

Flag that indicates whether the API credential is active.

last_login_at string

Indicates when the API credential was last used.

created_at string

Indicates when the API credential was created.

updated_at string

Indicates when the API credential was last updated.

secret string

API key password.
Example Response JSON
                    
  {
    "id": 1001,
    "key": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
    "client_id": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
    "is_active": false,
    "last_login_at": "2016-12-06T15:50:49.402Z",
    "created_at": "2016-12-06T15:50:49.402Z",
    "updated_at": "2016-12-06T15:50:49.402Z",
    "secret": "SX0LGy6z!Pa~,V-!A:az"
  }                  
                    
                  

Retrieve API Credential

Retrieve details for an API Credential.

Request Parameters

GET https://api.workpath.co/api-keys/[id OR key]

id number

optional if key is used

ID of the API Credential being requested.

key string

optional if id is used

Key of API Credential being requested.
Response Attributes

id number

API Key ID.

key string

API Key.

client_id string

Associated client ID.

is_active boolean

Flag that indicates whether the API credential is active.

last_login_at string

Indicates when the API credential was last used.

created_at string

Indicates when the API credential was created.

updated_at string

Indicates when the API credential was last updated.
Example Response JSON
                    
  {
    "id": 1001,
    "key": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
    "client_id": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
    "is_active": false,
    "last_login_at": "2016-12-06T15:50:49.402Z",
    "created_at": "2016-12-06T15:50:49.402Z",
    "updated_at": "2016-12-06T15:50:49.402Z"
  }                  
                    
                  

Retrieve API Credential List

GET https://api.workpath.co/api-keys/

Retrieve list of API Credentials associated with authenticating client.

Example Response JSON
                    
  [
    {
      "id": 1001,
      "key": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
      "client_id": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
      "is_active": false,
      "last_login_at": "2016-12-06T15:50:49.402Z",
      "created_at": "2016-12-06T15:50:49.402Z",
      "updated_at": "2016-12-06T15:50:49.402Z"
    },
    {
      "id": 1002,
      "key": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
      "client_id": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
      "is_active": true,
      "last_login_at": "2016-12-06T15:50:49.402Z",
      "created_at": "2016-12-06T15:50:49.402Z",
      "updated_at": "2016-12-06T15:50:49.402Z"
    },
    ...   
  ]                                    
                    
                  


Update API Credential

Modifies an individual API Credential.

Parameters

PUT https://api.workpath.co/api-keys/[key]

key string

optional

Key of the API Credential being updated.
Request Attributes

PUT https://api.workpath.co/api-keys/[key]

is_active string

Updates active status.
Response Attributes

id number

API Key ID.

key string

API Key.

client_id string

Associated client ID.

is_active boolean

Flag that indicates whether the API credential is active.

last_login_at string

Indicates when the API credential was last used.

created_at string

Indicates when the API credential was created.

updated_at string

Indicates when the API credential was last updated.

secret string

API key password.
Example Response JSON
                    
  {
    "id": 1001,
    "key": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
    "client_id": "c2b869e9-2013-4435-9eb9-837b0dc7937d",
    "is_active": false,
    "last_login_at": "2016-12-06T15:50:49.402Z",
    "created_at": "2016-12-06T15:50:49.402Z",
    "updated_at": "2016-12-06T15:50:49.402Z"
  }                  
                    
                  

Delete API Credential

Deletes a Device in a User.

Parameters

DELETE https://api.workpath.co/api-keys/[key]

key string

optional

Key of the API Credential being deleted.

Need additional assistance? Click Here

People

These are the endpoints you will need to hit in order to create a Patient, Guarantor, and an Insured Person for the Insurance Object later on.


Create A Person

Create a new Person.

Request Attributes

POST https://api.workpath.co/people

first_name string

required

Person's first name.

last_name string

required

Person's last name.

gender string

required

Gender of the Person.

biological_sex string

required

The biological sex of the Person. The following are accepted options: Ambiguous, Female, Male, Not Applicable, Other, or Unknown.

date_of_birth string

required

The Person's date of birth.

phone string

required

The Person's phone number. Please include the country code. For example, “8045551234” will not be accepted - please format as “+18045551234”.

email string

required

The Person's email address.

photo_url string

A link to the Person's profile picture if applicable.

messaging_enabled boolean

Is messaging enabled for the Person?

addresses array

required

An array of address objects. Each address object should have the following fields:

street string

required

The Person's street address.

street2 string

The Person's street address.

city string

required

The Person's city.

state string

required

The Person's state.

zip string

required

The Person's zip code.

country string

required

The Person's country.

phone string

The address's phone number.

latitude number

required

The latitude of the address for map purposes.

longitude number

required

The longitude of the address for map purposes.

timezone string

required

The address's timezone.
Example Request JSON
                    
  {
    "first_name": "Joseph",
    "last_name": "Schmoseph",
    "dob": "1977-06-01",
    "gender": "female",
    "biological_sex": "Female",
    "phone": "+17183211234",
    "email": "testguy@example.com",
    "photo_url": "https://example.com/pic.png",
    "messaging_enabled": true,
    "addresses": [
      {
        "id": 1001,
        "label": "Home",
        "street": "123 Fourth St",
        "street2": "Suite 101",
        "city": "Richmond",
        "state": "Virginia",
        "zip": "10001",
        "country": "US",
        "phone": "+17183211234",
        "latitude": 37.5407246,
        "longitude": -77.4360481,
        "timezone": "America/New_York"
      }
    ]
  }                                
                    
                  

Update A Person

Modify a Person.

Request Attributes

PUT https://api.workpath.co/people/[id]

first_name string

required

Person's first name.

last_name string

required

Person's last name.

gender string

required

Gender of the Person.

biological_sex string

required

The biological sex of the Person. The following are accepted options: Ambiguous, Female, Male, Not Applicable, Other, or Unknown.

date_of_birth string

required

The Person's date of birth.

phone string

required

The Person's phone number. Please include the country code. For example, “8045551234” will not be accepted - please format as “+18045551234”.

email string

required

The Person's email address.

photo_url string

A link to the Person's profile picture if applicable.

messaging_enabled boolean

Is messaging enabled for the Person?
Example Request JSON
                    
  {
    "first_name": "Joseph",
    "last_name": "Schmoseph",
    "dob": "1977-06-01",
    "gender": "female",
    "biological_sex": "Female",
    "phone": "+17183211234",
    "email": "testguy@example.com",
    "photo_url": "https://example.com/pic.png",
    "messaging_enabled": true
  }                                
                    
                  
Response Attributes

id number

The ID of the created Person.

first_name string

Person's first name.

last_name string

Person's last name.

gender string

Gender of the Person.

biological_sex string

required

The biological sex of the Person. The following are accepted options: Ambiguous, Female, Male, Not Applicable, Other, or Unknown.

date_of_birth string

The Person's date of birth.

phone string

The Person's phone number. Please include the country code. For example, “8045551234” will not be accepted - please format as “+18045551234”.

email string

The Person's email address.

photo_url string

A link to the Person's profile picture if applicable.

messaging_enabled boolean

Is messaging enabled for the Person?

addresses array

An array of address objects attached to the Person.

tags array

optional

An array of tag objects attached to the Person.

documents array

optional

An array of document objects attached to the Person.
Example Response JSON
                    
  {
    "id": 1001,
    "name": "Joseph Schmoseph",
    "dob": "1977-06-01",
    "gender": "female",
    "biological_sex": "Female",
    "phone": "+17183211234",
    "email": "testguy@example.com",
    "photo_url": "https://example.com/pic.png",
    "messaging_enabled": true,
    "addresses": [
      {
        "id": 1001,
        "label": "Home",
        "street": "123 Fourth St",
        "street2": "Suite 101",
        "city": "Richmond",
        "state": "Virginia",
        "zip": "10001",
        "country": "US",
        "phone": "+17183211234",
        "latitude": 37.5407246,
        "longitude": -77.4360481,
        "timezone": "America/New_York"
      }
    ],
    "tags": [
      {
        "id": 1001,
        "name": "Centrifuge",
        "color": "#FF0000",
        "description": "Lorem ipsum dolor sit amet",
        "locked": false,
        "alert": false,
        "organization_id": null
      }
    ],
    "documents": [
      {
        "id": 1001,
        "name": "Certification",
        "url": "https://example.com/certification"
      }
    ]
  }                               
                    
                  

Retrieve Person

Retrieve details for a Person.

Request Parameters

GET https://api.workpath.co/people/[id]

id number

required

ID of the Person being requested.
Response Attributes

id number

The ID of the created Person.

first_name string

Person's first name.

last_name string

Person's last name.

gender string

Gender of the Person.

biological_sex string

required

The biological sex of the Person. The following are accepted options: Ambiguous, Female, Male, Not Applicable, Other, or Unknown.

date_of_birth string

The Person's date of birth.

phone string

The Person's phone number. Please include the country code. For example, “8045551234” will not be accepted - please format as “+18045551234”.

email string

The Person's email address.

photo_url string

A link to the Person's profile picture if applicable.

messaging_enabled boolean

Is messaging enabled for the Person?

addresses array

An array of address objects attached to the Person.

tags array

optional

An array of tag objects attached to the Person.

documents array

optional

An array of document objects attached to the Person.
Example Response JSON
                    
  {
    "id": 1001,
    "name": "Joseph Schmoseph",
    "dob": "1977-06-01",
    "gender": "female",
    "biological_sex": "Female",
    "phone": "+17183211234",
    "email": "testguy@example.com",
    "photo_url": "https://example.com/pic.png",
    "messaging_enabled": true,
    "addresses": [
      {
        "id": 1001,
        "label": "Home",
        "street": "123 Fourth St",
        "street2": "Suite 101",
        "city": "Richmond",
        "state": "Virginia",
        "zip": "10001",
        "country": "US",
        "phone": "+17183211234",
        "latitude": 37.5407246,
        "longitude": -77.4360481,
        "timezone": "America/New_York"
      }
    ],
    "tags": [
      {
        "id": 1001,
        "name": "Centrifuge",
        "color": "#FF0000",
        "description": "Lorem ipsum dolor sit amet",
        "locked": false,
        "alert": false,
        "organization_id": null
      }
    ],
    "documents": [
      {
        "id": 1001,
        "name": "Certification",
        "url": "https://example.com/certification"
      }
    ]
  }                               
                    
                  

Delete Person

Deletes a Person.

Parameters

DELETE https://api.workpath.co/people/[id]

id string

ID of the Person being deleted.

Need additional assistance? Click Here

Payment Object

If you do not know this information, simply send us an empty object and we will request the information from your patient directly.

Request Attributes

person_id number

required

The Patient's created Workpath ID.

insurance_details_id number

optional if patient is self-pay

Workpath ID for created insurance details.

payment_type string

required

This will be either patient insurance or self-pay.
Example Payment JSON
                    
  {
    "person_id": 0,
    "insurance_details_id": 0,
    "payment_type": ""
  }                                 
                    
                  

Need additional assistance? Click Here

COMING SOON!

Patient Insurance Information Object

The ability to record patient insurance information is something we are currently working on, but here is a peek at what the insurance information will look like:

If you do not know this information, simply send us an empty object and we will request the information from your patient directly. This information is only needed if your patient has insurance that they will be using to pay for the requested labs/tests.

It is important to note that in order to have a guarantor_id and an insured_person_id, you must create those people by using the people endpoint.

Request Attributes

person_id number

required

Workpath ID of the created Patient.

company_name string

required

Name of Patient's Insurance Company.

company_address object

required

Address of the patient’s insurance company.

street string

required

The insurance company’s street address.

street2 string

required

The insurance company’s street address.

city string

required

The insurance company’s city.

state string

required

The insurance company’s state.

zip string

required

The insurance company’s zip code.

country string

required

The insurance company’s country.

company_phone string

required

Patient’s insurance company phone number including country code. “+18045551234”

group_number string

required

Group number for patient’s insurance policy.

relationship string

required

The relationship of the patient to the policy holder.

policy_number string

required

The policy number for the patient’s insurance policy.

guarantor_id number

required

The Guarantor Person's created Workpath ID. (see People)

insured_person_id number

required

The Insured Person's created Workpath ID. (see People)
Example Insurance JSON
                    
  {
    "person_id": 0, 
    "company_name": "",
    "company_address": {
      "street": "",
      "street2": "",
      "city": "",
      "state": "",
      "zip": "",
      "country": "",
    },
    "company_phone": "",
    "group_number": "",
    "relationship": "",
    "policy_number": "",
    "guarantor_id": 0, // person.id
    "insured_person_id": 0 // person.id
  }                                
                    
                  

Need additional assistance? Click Here

Intakes

The Intake is the starting point for a patient request. The initial call takes in certain parameters about the patient and the service being ordered and, depending on the Order Form that is specified, sends a request to the patient (via email and/or SMS) for additional information.


Patient Requests

When creating an Intake, the attached Order Form (order_form) determines the behavior of the Intake as it progresses through the system.

When an Order Form contains Patient Fields, a Patient Request is sent to the patient for those details. However, if those Patient Fields are already populated by the initial creation call, the Patient Request will not be sent since no data is required from the Patient.

The Order Form also determines how the Intake will advance once all required details are provided:

  • If the Order Form is set to Auto-Publish, the Intake will be automatically converted to an Appointment.
  • If not, the Intake will populate within the "New" tab of the Service Requests tab on the web app. An Office User can then verify the Intake and convert it to an Appointment.

Intake Object

Fetch an Intake: GET https://api.workpath.co/intakes/[id]

Intake Object Attributes

id integer

The Intake's unique ID

order_form integer

The unique ID of the Order Form that is attached to this Intake

provider Provider object

The physician or prescribing entity that requested the service

id integer

The Provider's unique ID

first_name string

The Provider's first name

last_name string

The Provider's last name

email string

The Provider's email address

phone string

The Provider's phone number

organization_name string

The Provider's organization name

npi string

The Provider's National Provider Identifier (NPI)

status string

The verification status of the Provider

patient Patient object

The Patient

id integer

The Patient's unique ID

first_name string

The Patient's legal first name

middle_name string

The Patient's middle name

last_name string

The Patient's legal last name

phone string

The Patient's phone number

email string

The Patient's email address

biological_sex string

The Patient's biological sex

gender string

The Patient's gender

messaging_enabled_sms boolean

Determines whether the patient should receive SMS messages. If using patient patients and this is enabled, an email address must be provided.

messaging_enabled_email boolean

Determines whether the patient should receive emails. If using patient requests and no phone number is provided, this is ignored for the purposes of sending the patient request.

services array of objects

The requested services and their related ICD-10 codes

id number

The Service's unique ID

diagnosis_codes array of strings

The ICD-10 codes for the conditions applicable to the test

start_time string

The requested start time of the service

location Location object

The address for the service

id integer

The Address's unique ID

street string

The location's street address

street2 string

The location's second address line (apartment, suite, etc.)

city string

The location's city

state string

The location's state

zip string

The location's zip code or postal code

country string

The location's country as a two-letter code (e.g. "US")

latitude float

The location's latitude

longitude float

The location's longitude

notes string

Notes from the provider or ordering entity intended for the labor provider

fields array of Custom Field objects

Any custom data for the Intake

key string

The field's unique key

show boolean

Controls the visibility of the field

required boolean

Determines whether the field is required or not

value any valid JSON type

The current value of the custom field

big boolean

Determines the presentation of the field (false = text field, true = text box)

patient_fields array of Custom Field objects

Any custom data that the patient would fill out

key string

The field's unique key

show boolean

Controls the visibility of the field

required boolean

Determines whether the field is required or not

value any valid JSON type

The current value of the custom field

big boolean

Determines the presentation of the field (false = text field, true = text box)

appointment integer

The ID of the appointment that was created from this intake (if it has been converted)
Example Intake Object JSON
                    
  {
    "id": 92200,
    "order_form": 1,
    "provider": {
      "id": 12313,
      "first_name": "Bruce",
      "last_name": "Banner",
      "npi": "0101010111",
      "status": "active"
    },
    "patient": {
      "id": 312391,
      "first_name": "Anthony",
      "middle_name": "Edward",
      "last_name": "Stark",
      "biological_sex": "male",
      "gender": "male",
      "phone": "8048675309",
      "email": "tony@starkindustries.com",
      "messaging_enabled_sms": true,
      "messaging_enabled_email": true
    },
    "services": [
      { "id": 12312, "diagnosis_codes": ["Z00.12", "H879.3"] },
      { "id": 91232, "diagnosis_codes": ["H879.3"] }
    ],
    "start_time": "2021-06-20T13:00:00Z",
    "location": {
      "id": 912012,
      "street": "200 Park Avenue",
      "street2": "The Top",
      "city": "New York",
      "state": "New York",
      "zip": "10166",
      "country": "US",
      "latitude": 40.7533488,
      "longitude": -73.9788555
    },
    "notes": "Patient has fusion reactor in chest."
  }                                    
                    
                  

Create an Intake

POST https://api.workpath.co/intakes

Request Attributes

order_form integer

The unique ID of the Order Form that is attached to this Intake

provider Provider object

The physician or prescribing entity that requested the service

id integer

The Provider's unique ID

first_name string

The Provider's first name

last_name string

The Provider's last name

email string

The Provider's email address

phone string

The Provider's phone number

organization_name string

The Provider's organization name

npi string

The Provider's National Provider Identifier (NPI)

status string

The verification status of the Provider

patient Patient object

The Patient

id integer

The Patient's unique ID

first_name string

The Patient's legal first name

middle_name string

The Patient's middle name

last_name string

The Patient's legal last name

phone string

The Patient's phone number

email string

The Patient's email address

biological_sex string

The Patient's biological sex

gender string

The Patient's gender

messaging_enabled_sms boolean

Determines whether the patient should receive SMS messages. If using patient patients and this is enabled, an email address must be provided.

messaging_enabled_email boolean

Determines whether the patient should receive emails. If using patient requests and no phone number is provided, this is ignored for the purposes of sending the patient request.

services array of objects

The requested services and their related ICD-10 codes

id number

The Service's unique ID

diagnosis_codes array of strings

The ICD-10 codes for the conditions applicable to the test

start_time string

The requested start time of the service

location Location object

The address for the service

id integer

The Address's unique ID

street string

The location's street address

street2 string

The location's second address line (apartment, suite, etc.)

city string

The location's city

state string

The location's state

zip string

The location's zip code or postal code

country string

The location's country as a two-letter code (e.g. "US")

latitude float

The location's latitude

longitude float

The location's longitude

notes string

Notes from the provider or ordering entity intended for the labor provider

fields array of Custom Field objects

Any custom data for the Intake

key string

The field's unique key

show boolean

Controls the visibility of the field

required boolean

Determines whether the field is required or not

value any valid JSON type

The current value of the custom field

big boolean

Determines the presentation of the field (false = text field, true = text box)

patient_fields array of Custom Field objects

Any custom data that the patient would fill out

key string

The field's unique key

show boolean

Controls the visibility of the field

required boolean

Determines whether the field is required or not

value any valid JSON type

The current value of the custom field

big boolean

Determines the presentation of the field (false = text field, true = text box)

Need additional assistance? Click Here


Upload Intake Document

POST https://api.workpath.co/intakes/[:id]/documents

Attaching documents to Intakes is done via the Upload Intake Document endpoint.

Headers
Content-Type: multipart/form-data
Authorization: Bearer ut11023123...
Parameters

file

required

MIME data
Upload Document Response JSON
                    
  {
    "id": 1001,
    "name": "test-file.pdf",
    "url": "https://s3.amazonaws.com/.../...",
    "api_url": "https://api.workpath.co/.../...",
    "documentable": "intake",
    "documentable_id": 9402,
    "created_at": "2021-06-17T12:00:00Z",
    "updated_at": "2021-06-17T12:00:00Z"
  }                                  
                    
                  

Need additional assistance? Click Here

Appointments

Appointments are the central Workpath data model, representing the scheduled time and place where a Specialist performs a set of Services.

Possible status values for Appointments are:

  • Preview - a "holding" status for an appointment, only visible to office users on their dashboard
  • Pending - a "holding" status for an appointment, only visible to office users on their dashboard
  • Available - the appointment is available for third-party labor groups in your network to claim/fulfill
  • Claimed - the appointment has been claimed by the third-party labor group who will be servicing the appointment
  • Published - the appointment has been published to qualified the mobile users around the appointment location for self-assignment
  • Accepted - the appointment has been accepted or assigned to a mobile user
  • Ready for Appointment - the mobile user has confirmed they have reviewed appointment details and have all necessary supplies to complete appointment
  • On The Way - the mobile user has indicated they are en route to the appointment
  • Arrived - the mobile user has indicated they have arrived to the appointment
  • In Progress - the appointment is in progress
  • Shipping - if shipping was a required step, the mobile user is being prompted to scan the tracking # on the package
  • Complete - the appointment has been completed
  • Cancelled - the appointment has been cancelled

By default, only appointments with a Published status are visible to users. If a User is associated with an Appointment as the assigned Specialist, the creator of the appointment, or the subject of the appointment, then the appointment will be visible for all the other status values as well as Published.

Sample Appointment Response JSON
                    
  {
    "id": 0,
    "status": "Accepted",
    "type": "Single",
    "start_time": "2016-09-23T18:25:43.511Z",
    "end_time": "2016-09-23T19:00:43.511Z",
    "published_at": "2016-09-19T19:00:43.511Z",
    "specialists_needed": 1,
    "specialists_accepted": 0,
    "specialist_payment": 75,
    "alt_id": null,
    "medical_record_number": null,
    "parent_id": null,
    "authorized": false,
    "requirements_message": "Requires centrifuge",
    "location": {
      "id": 1001,
      "label": "Home",
      "street": "123 Fourth St",
      "street2": "Suite 101",
      "city": "Richmond",
      "state": "Virginia",
      "zip": "10001",
      "country": "US",
      "phone": "+17183211234",
      "latitude": 37.5407246,
      "longitude": -77.4360481,
      "timezone": "America/New_York"
    },
    "originator": {
      "id": 1001,
      "name": "XYZ Cardiology",
      "description": "Demo organization",
      "phone": "+17183211234",
      "website": "http://examplecorp.com/",
      "logo_url": "http://example.com/logo.png",
      "disable_claimed_status": false,
      "disable_available_status": false,
      "customer_contact_phone": "+17183211234",
      "customer_contact_email": "one@example.com",
      "merchant_id": null,
      "customer_id": null,
      "payment_id": null,
      "braintree_id": null,
      "prepayment_amount": 1000,
      "tiered_transactions": true,
      "users_included": 5,
      "addl_user_charge": 49.99,
      "management_fee": 0,
      "organizable": "vendor",
      "organizable_id": 1001,
      "addresses": [
        {
          "id": 1001,
          "label": "Home",
          "street": "123 Fourth St",
          "street2": "Suite 101",
          "city": "Richmond",
          "state": "Virginia",
          "zip": "10001",
          "country": "US",
          "phone": "+17183211234",
          "latitude": 37.5407246,
          "longitude": -77.4360481,
          "timezone": "America/New_York"
        }
      ],
      "tags": [
        {
          "id": 1001,
          "name": "Centrifuge",
          "color": "#FF0000",
          "description": "Lorem ipsum dolor sit amet",
          "locked": false,
          "alert": false,
          "organization_id": null
        }
      ],
      "preferences": [
        {
          "id": null,
          "name": "",
          "value": null
        }
      ]
    },
    "distributor": {
      "id": 1001,
      "name": "XYZ Cardiology",
      "description": "Demo organization",
      "phone": "+17183211234",
      "website": "http://examplecorp.com/",
      "logo_url": "http://example.com/logo.png",
      "disable_claimed_status": false,
      "disable_available_status": false,
      "customer_contact_phone": "+17183211234",
      "customer_contact_email": "one@example.com",
      "merchant_id": null,
      "customer_id": null,
      "payment_id": null,
      "braintree_id": null,
      "prepayment_amount": 1000,
      "tiered_transactions": true,
      "users_included": 5,
      "addl_user_charge": 49.99,
      "management_fee": 0,
      "organizable": "vendor",
      "organizable_id": 1001,
      "addresses": [
        {
          "id": 1001,
          "label": "Home",
          "street": "123 Fourth St",
          "street2": "Suite 101",
          "city": "Richmond",
          "state": "Virginia",
          "zip": "10001",
          "country": "US",
          "phone": "+17183211234",
          "latitude": 37.5407246,
          "longitude": -77.4360481,
          "timezone": "America/New_York"
        }
      ],
      "tags": [
        {
          "id": 1001,
          "name": "Centrifuge",
          "color": "#FF0000",
          "description": "Lorem ipsum dolor sit amet",
          "locked": false,
          "alert": false,
          "organization_id": null
        }
      ],
      "preferences": [
        {
          "id": null,
          "name": "",
          "value": null
        }
      ]
    },
    "data": [
      {
        "id": 1001,
        "value": "0123456789",
        "label": "Shipping ID",
        "type": "shipping"
      }
    ],
    "network": [
      {
        "id": 1001
      }
    ],
    "subject": {
      "id": 1001,
      "name": "Joseph Schmoseph",
      "dob": "1977-06-01",
      "gender": "female",
      "phone": "+17183211234",
      "email": "testguy@example.com",
      "photo_url": "http://example.com/pic.png",
      "addresses": [
        {
          "id": 1001,
          "label": "Home",
          "street": "123 Fourth St",
          "street2": "Suite 101",
          "city": "Richmond",
          "state": "Virginia",
          "zip": "10001",
          "country": "US",
          "phone": "+17183211234",
          "latitude": 37.5407246,
          "longitude": -77.4360481,
          "timezone": "America/New_York"
        }
      ],
      "tags": [
        {
          "id": 1001,
          "name": "Centrifuge",
          "color": "#FF0000",
          "description": "Lorem ipsum dolor sit amet",
          "locked": false,
          "alert": false,
          "organization_id": null
        }
      ],
      "documents": [
        {
          "id": 1001,
          "name": "Certification",
          "url": "https://example.com/certification"
        }
      ]
    },
    "creator": {
      "id": 1001,
      "is_admin": false,
      "email": "user@example.com",
      "email_verified_at": "2016-09-23T18:25:43.511Z",
      "last_login_at": "2016-09-23T18:25:43.511Z",
      "tos_accepted_at": "2016-09-23T18:25:43.511Z",
      "type": [
        "Organization, Specialist"
      ],
      "latitude": 37.5407246,
      "longitude": -77.4360481,
      "gps_updated_at": null,
      "home_radius": 60,
      "location_radius": 60,
      "devices": [
        {
          "id": "nachou9e8o0e7",
          "type": "android",
          "created_at": "2019-07-01T20:45:54.000Z",
          "updated_at": "2019-07-01T20:45:54.000Z",
          "user_id": 1001
        }
      ],
      "person": {
        "id": 1001,
        "name": "Joseph Schmoseph",
        "dob": "1977-06-01",
        "gender": "female",
        "phone": "+17183211234",
        "email": "testguy@example.com",
        "photo_url": "http://example.com/pic.png",
        "addresses": [
          {
            "id": 1001,
            "label": "Home",
            "street": "123 Fourth St",
            "street2": "Suite 101",
            "city": "Richmond",
            "state": "Virginia",
            "zip": "10001",
            "country": "US",
            "phone": "+17183211234",
            "latitude": 37.5407246,
            "longitude": -77.4360481,
            "timezone": "America/New_York"
          }
        ],
        "tags": [
          {
            "id": 1001,
            "name": "Centrifuge",
            "color": "#FF0000",
            "description": "Lorem ipsum dolor sit amet",
            "locked": false,
            "alert": false,
            "organization_id": null
          }
        ],
        "documents": [
          {
            "id": 1001,
            "name": "Certification",
            "url": "https://example.com/certification"
          }
        ]
      },
      "organizations": [
        {
          "id": 1001,
          "name": "XYZ Cardiology",
          "global_id": "pgsk*a08098fad",
          "description": "Demo organization",
          "phone": "+17183211234",
          "website": "http://examplecorp.com/",
          "logo_url": "http://example.com/logo.png",
          "disable_claimed_status": false,
          "disable_available_status": false,
          "customer_contact_phone": "+17183211234",
          "customer_contact_email": "one@example.com",
          "merchant_id": null,
          "customer_id": null,
          "payment_id": null,
          "braintree_id": null,
          "prepayment_amount": 1000,
          "tiered_transactions": true,
          "users_included": 5,
          "addl_user_charge": 49.99,
          "management_fee": 0,
          "organizable": "vendor",
          "organizable_id": 1001,
          "vendor": {
            "id": 1001,
            "default_service_fee": 100,
            "default_specialist_percentage": 0,
            "organization": {
              "id": 1001,
              "name": "XYZ Cardiology",
              "description": "Demo organization",
              "phone": "+17183211234",
              "website": "http://examplecorp.com/",
              "logo_url": "http://example.com/logo.png",
              "disable_claimed_status": false,
              "disable_available_status": false,
              "customer_contact_phone": "+17183211234",
              "customer_contact_email": "one@example.com",
              "merchant_id": null,
              "customer_id": null,
              "payment_id": null,
              "braintree_id": null,
              "prepayment_amount": 1000,
              "tiered_transactions": true,
              "users_included": 5,
              "addl_user_charge": 49.99,
              "management_fee": 0,
              "organizable": "vendor",
              "organizable_id": 1001,
              "addresses": [
                {
                  "id": 1001,
                  "label": "Home",
                  "street": "123 Fourth St",
                  "street2": "Suite 101",
                  "city": "Richmond",
                  "state": "Virginia",
                  "zip": "10001",
                  "country": "US",
                  "phone": "+17183211234",
                  "latitude": 37.5407246,
                  "longitude": -77.4360481,
                  "timezone": "America/New_York"
                }
              ],
              "tags": [
                {
                  "id": 1001,
                  "name": "Centrifuge",
                  "color": "#FF0000",
                  "description": "Lorem ipsum dolor sit amet",
                  "locked": false,
                  "alert": false,
                  "organization_id": null
                }
              ],
              "preferences": [
                {
                  "id": null,
                  "name": "",
                  "value": null
                }
              ]
            },
            "services": [
              {
                "id": 1001,
                "vendor": {
                  "id": 1001
                },
                "name": "Blood Draw",
                "description": "A standard blood draw",
                "vendor_fee": 60,
                "specialist_payment": 40,
                "duration": 15,
                "shippable": false,
                "archived": false,
                "tags": [
                  {
                    "id": 1001,
                    "name": "Centrifuge",
                    "color": "#FF0000",
                    "description": "Lorem ipsum dolor sit amet",
                    "locked": false,
                    "alert": false,
                    "organization_id": null
                  }
                ],
                "steps": [
                  {
                    "id": 1001,
                    "rank": 10,
                    "title": "Package tube",
                    "description": "Fill the tube",
                    "address": {
                      "label": "Home",
                      "street": "123 Fourth St",
                      "street2": "Suite 101",
                      "city": "Richmond",
                      "state": "Virginia",
                      "zip": "10001",
                      "country": "US",
                      "phone": "+17183211234",
                      "latitude": 37.5407246,
                      "longitude": -77.4360481,
                      "timezone": "America/New_York"
                    },
                    "type": "action",
                    "stage": "pre"
                  }
                ]
              }
            ]
          },
          "roles": {
            "office_user": false,
            "mobile_user": false,
            "orderer": false
          },
          "preferences": [
            {
              "id": null,
              "name": "",
              "value": null
            }
          ]
        }
      ]
    },
    "specialist": {
      "id": 1001,
      "person": {
        "id": 1001,
        "name": "Joseph Schmoseph",
        "dob": "1977-06-01",
        "gender": "female",
        "phone": "+17183211234",
        "email": "testguy@example.com",
        "photo_url": "http://example.com/pic.png",
        "addresses": [
          {
            "id": 1001,
            "label": "Home",
            "street": "123 Fourth St",
            "street2": "Suite 101",
            "city": "Richmond",
            "state": "Virginia",
            "zip": "10001",
            "country": "US",
            "phone": "+17183211234",
            "latitude": 37.5407246,
            "longitude": -77.4360481,
            "timezone": "America/New_York"
          }
        ],
        "tags": [
          {
            "id": 1001,
            "name": "Centrifuge",
            "color": "#FF0000",
            "description": "Lorem ipsum dolor sit amet",
            "locked": false,
            "alert": false,
            "organization_id": null
          }
        ],
        "documents": [
          {
            "id": 1001,
            "name": "Certification",
            "url": "https://example.com/certification"
          }
        ]
      },
      "status": "Applicant",
      "application_score": 85,
      "quality_rating": 50,
      "tags": [
        {
          "id": 1001,
          "name": "Centrifuge",
          "color": "#FF0000",
          "description": "Lorem ipsum dolor sit amet",
          "locked": false,
          "alert": false,
          "organization_id": null
        }
      ],
      "merchant_id `abc123`": null,
      "payment_id `paymentabc123`": null,
      "braintree_id `braintreeabc123`": null
    },
    "services": [
      {
        "id": 1001,
        "vendor": {
          "id": 1001
        },
        "name": "Blood Draw",
        "description": "A standard blood draw",
        "vendor_fee": 60,
        "specialist_payment": 40,
        "duration": 15,
        "shippable": false,
        "archived": false,
        "tags": [
          {
            "id": 1001,
            "name": "Centrifuge",
            "color": "#FF0000",
            "description": "Lorem ipsum dolor sit amet",
            "locked": false,
            "alert": false,
            "organization_id": null
          }
        ],
        "steps": [
          {
            "id": 1001,
            "rank": 10,
            "title": "Package tube",
            "description": "Fill the tube",
            "address": {
              "label": "Home",
              "street": "123 Fourth St",
              "street2": "Suite 101",
              "city": "Richmond",
              "state": "Virginia",
              "zip": "10001",
              "country": "US",
              "phone": "+17183211234",
              "latitude": 37.5407246,
              "longitude": -77.4360481,
              "timezone": "America/New_York"
            },
            "type": "action",
            "stage": "pre"
          }
        ]
      }
    ],
    "tags": [
      {
        "id": 1001,
        "name": "Centrifuge",
        "color": "#FF0000",
        "description": "Lorem ipsum dolor sit amet",
        "locked": false,
        "alert": false,
        "organization_id": null
      }
    ],
    "documents": [
      {
        "id": 1001,
        "name": "Certification",
        "url": "https://example.com/certification"
      }
    ],
    "payment_status": "Pending",
    "payment_amount": 25
  }                    
                    
                  

Update Appointment

PUT https://api.workpath.co/appointments/[id]

Modifies an individual appointment. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.
Request Attributes

status string

Appointment status.

type string

Type of appointment. One of 'Single','Shift'.

published_at string

Publishing time of appointment.

specialists_needed number

Number of Specialists needed for this appointment.

specialist_payment number

Amount Specialist earns for this appointment.

alt_id string

Third party ID value.

medical_record_number number

MRN value.

requisition_id string

Requisition ID.

parent_id number

Parent ID value.

location Location object

The address for the service

id integer

The Address's unique ID

street string

The location's street address

street2 string

The location's second address line (apartment, suite, etc.)

city string

The location's city

state string

The location's state

zip string

The location's zip code or postal code

country string

The location's country as a two-letter code (e.g. "US")

latitude float

The location's latitude

longitude float

The location's longitude

distributor object

Organization ID that is responsible for appointment fulfillment.

id number

required

Distributing organization ID.

subject Patient object

The Patient

id integer

The Patient's unique ID

first_name string

The Patient's legal first name

middle_name string

The Patient's middle name

last_name string

The Patient's legal last name

phone string

The Patient's phone number

email string

The Patient's email address

biological_sex string

The Patient's biological sex

gender string

The Patient's gender

messaging_enabled_sms boolean

Determines whether the patient should receive SMS messages. If using patient patients and this is enabled, an email address must be provided.

messaging_enabled_email boolean

Determines whether the patient should receive emails. If using patient requests and no phone number is provided, this is ignored for the purposes of sending the patient request.

specialist object

Specialist assigned to this appointment.

id number

required

Specialist ID.

payment_status string

Disposition of outgoing payment to distributor/specialist.

payment_amount number

Amount that the distributor/specialist will receive as payment.

network Array[objects]

Organization IDs with appointment visibility when status is 'Available'.

id number

required

Organization ID.
Request JSON
                    
  {
    "status": "Accepted",
    "type": "Single",
    "published_at": "2016-09-19T19:00:43.511Z",
    "specialists_needed": 1,
    "specialist_payment": 75,
    "location": {
      "id": 1001,
      "label": "Home",
      "street": "123 Fourth St",
      "street2": "Suite 101",
      "city": "Richmond",
      "state": "Virginia",
      "zip": "10001",
      "country": "US",
      "phone": "+17183211234",
      "latitude": 37.5407246,
      "longitude": -77.4360481,
      "timezone": "America/New_York"
    },
    "distributor": {
      "id": 1001
    },
    "subject": {
      "id": 1001,
      "name": "Joseph Schmoseph",
      "dob": "1977-06-01",
      "gender": "female",
      "phone": "+17183211234",
      "email": "testguy@example.com",
      "photo_url": "http://example.com/pic.png",
      "addresses": [
        {
          "id": 1001,
          "label": "Home",
          "street": "123 Fourth St",
          "street2": "Suite 101",
          "city": "Richmond",
          "state": "Virginia",
          "zip": "10001",
          "country": "US",
          "phone": "+17183211234",
          "latitude": 37.5407246,
          "longitude": -77.4360481,
          "timezone": "America/New_York"
        }
      ],
      "tags": [
        {
          "id": 1001,
          "name": "Centrifuge",
          "color": "#FF0000",
          "description": "Lorem ipsum dolor sit amet",
          "locked": false,
          "alert": false,
          "organization_id": null
        }
      ],
      "documents": [
        {
          "id": 1001,
          "name": "Certification",
          "url": "https://example.com/certification"
        }
      ]
    },
    "specialist": {
      "id": 1001
    },
    "network": [
      {
        "id": 1001
      }
    ]
  }
                    
                  

Retrieve Appointment

GET https://api.workpath.co/appointments/[id]

Retrieve details for an individual appointment.

Request Parameters

id number

required

Appointment ID.

Retrieve Appointment List

GET https://api.workpath.co/appointments?[optional search parameters]

Retrieve a list of appointments, optionally filtered to match search criteria.

Search Parameters

page number

Page number of appointments to return.

limit number

Number of appointments to return per page.

lat number

Latitude of search center point.

lon number

Longitude of search center point.

radius number

Search radius in miles.

from number

Search start date (Unix timestamp)

until number

Searche end date (Unix timestamp)

status Array[string]

Filter results by status value.

type string

Filter results by type ('Single','Shift').

authorized string

Filter results by whether the current user is authorized to accept.

newestFirst string

Order results by start time. Default false.

specialist number

Filter results by assigned Specialist ID.

specialistName string

Filter results by assigned Specialist name.

subject number

Filter results by assigned Subject ID.

subjectName string

Filter results by assigned Subject name.

creator number

Filter results by assigned Creator ID.

creatorName string

Filter results by assigned Creator name.

vendor number

Filter results by assigned Vendor ID.

vendorName string

Filter results by assigned Vendor name.

service number

Filter results by assigned Service ID.

serviceName string

Filter results by assigned Service name.

parentId number

Filter for appointments with the provided parent_id.

unscheduled string

Filters appointments based on unscheduled status. Default exclude.
  • only returns only the unscheduled appointments
  • include returns unscheduled appointments and scheduled appointments
  • exclude returns only scheduled appointments (Default)
Sample Search Parameters String
page=1&limit=25&lat=37.5407246&lon=-77.4360481&radius=10&from=1474557817&until=1474593817&type=Single&authorized=true&newestFirst=false&specialist=1004&specialistName=Doe&subject=1004&subjectName=Doe&creator=1004&creatorName=Doe&vendor=1004&vendorName=Doe&service=1004&serviceName=Doe&parentId=1001&unscheduled=exclude

Cancel Appointment

POST https://api.workpath.co/appointments/[id]/cancel

Cancel appointment. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.

Misc. Appointment Calls

The calls listed in this section are used for aspects of appointments that have their own routes in our API: Tags, Notes, Documents, and Appointment Data that has been collected.

Add Tag to Appointment

POST https://api.workpath.co/appointments/[id]/tags

Apply Tag to a Appointment. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.
Request Attributes

id number

required

Tag ID.

expires_at string

Tag expiration timestamp.
Request JSON
                    
  {
    "tag": {
      "id": 1001,
      "expires_at": "2017-09-09T09:09:09Z"
    }
  }
                    
                  

Delete Tag in Appointment

DELETE https://api.workpath.co/appointments/[id]/tags/[tagid]

Deletes a tag in an appointment. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.

tagid number

required

Tag ID.

Add Note to Appointment

POST https://api.workpath.co/appointments/[id]/notes

Apply note to an appointment. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.
Request Attributes

body string

Note body.

type string

Type of note.

title string

Title of note.
Request JSON
                    
  {
    "body": "Note body",
    "type": "Warning",
    "title": "Admin Note"
  }
                    
                  
Response Attributes

id number

Note ID.

author object

**PUT STUFF HERE**

body string

Body of the note.

type string

required

Type of note.

title string

Title of the note.
Note Response JSON
                    
  {
    "id": 1001,
    "author": {
      "id": 1001,
      "is_admin": false,
      "email": "user@example.com",
      "email_verified_at": "2016-09-23T18:25:43.511Z",
      "last_login_at": "2016-09-23T18:25:43.511Z",
      "tos_accepted_at": "2016-09-23T18:25:43.511Z",
      "type": [
        "Organization, Specialist"
      ],
      "latitude": 37.5407246,
      "longitude": -77.4360481,
      "gps_updated_at": null,
      "home_radius": 60,
      "location_radius": 60,
      "devices": [
        {
          "id": "nachou9e8o0e7",
          "type": "android",
          "created_at": "2019-07-01T20:45:54.000Z",
          "updated_at": "2019-07-01T20:45:54.000Z",
          "user_id": 1001
        }
      ],
      "person": {
        "id": 1001,
        "name": "Joseph Schmoseph",
        "dob": "1977-06-01",
        "gender": "female",
        "phone": "+17183211234",
        "email": "testguy@example.com",
        "photo_url": "http://example.com/pic.png",
        "addresses": [
          {
            "id": 1001,
            "label": "Home",
            "street": "123 Fourth St",
            "street2": "Suite 101",
            "city": "Richmond",
            "state": "Virginia",
            "zip": "10001",
            "country": "US",
            "phone": "+17183211234",
            "latitude": 37.5407246,
            "longitude": -77.4360481,
            "timezone": "America/New_York"
          }
        ],
        "tags": [
          {
            "id": 1001,
            "name": "Centrifuge",
            "color": "#FF0000",
            "description": "Lorem ipsum dolor sit amet",
            "locked": false,
            "alert": false,
            "organization_id": null
          }
        ],
        "documents": [
          {
            "id": 1001,
            "name": "Certification",
            "url": "https://example.com/certification"
          }
        ]
      },
      "organizations": [
        {
          "id": 1001,
          "name": "XYZ Cardiology",
          "global_id": "pgsk*a08098fad",
          "description": "Demo organization",
          "phone": "+17183211234",
          "website": "http://examplecorp.com/",
          "logo_url": "http://example.com/logo.png",
          "disable_claimed_status": false,
          "disable_available_status": false,
          "customer_contact_phone": "+17183211234",
          "customer_contact_email": "one@example.com",
          "merchant_id": null,
          "customer_id": null,
          "payment_id": null,
          "braintree_id": null,
          "prepayment_amount": 1000,
          "tiered_transactions": true,
          "users_included": 5,
          "addl_user_charge": 49.99,
          "management_fee": 0,
          "organizable": "vendor",
          "organizable_id": 1001,
          "vendor": {
            "id": 1001,
            "default_service_fee": 100,
            "default_specialist_percentage": 0,
            "organization": {
              "id": 1001,
              "name": "XYZ Cardiology",
              "description": "Demo organization",
              "phone": "+17183211234",
              "website": "http://examplecorp.com/",
              "logo_url": "http://example.com/logo.png",
              "disable_claimed_status": false,
              "disable_available_status": false,
              "customer_contact_phone": "+17183211234",
              "customer_contact_email": "one@example.com",
              "merchant_id": null,
              "customer_id": null,
              "payment_id": null,
              "braintree_id": null,
              "prepayment_amount": 1000,
              "tiered_transactions": true,
              "users_included": 5,
              "addl_user_charge": 49.99,
              "management_fee": 0,
              "organizable": "vendor",
              "organizable_id": 1001,
              "addresses": [
                {
                  "id": 1001,
                  "label": "Home",
                  "street": "123 Fourth St",
                  "street2": "Suite 101",
                  "city": "Richmond",
                  "state": "Virginia",
                  "zip": "10001",
                  "country": "US",
                  "phone": "+17183211234",
                  "latitude": 37.5407246,
                  "longitude": -77.4360481,
                  "timezone": "America/New_York"
                }
              ],
              "tags": [
                {
                  "id": 1001,
                  "name": "Centrifuge",
                  "color": "#FF0000",
                  "description": "Lorem ipsum dolor sit amet",
                  "locked": false,
                  "alert": false,
                  "organization_id": null
                }
              ],
              "preferences": [
                {
                  "id": null,
                  "name": "",
                  "value": null
                }
              ]
            },
            "services": [
              {
                "id": 1001,
                "vendor": {
                  "id": 1001
                },
                "name": "Blood Draw",
                "description": "A standard blood draw",
                "vendor_fee": 60,
                "specialist_payment": 40,
                "duration": 15,
                "shippable": false,
                "archived": false,
                "tags": [
                  {
                    "id": 1001,
                    "name": "Centrifuge",
                    "color": "#FF0000",
                    "description": "Lorem ipsum dolor sit amet",
                    "locked": false,
                    "alert": false,
                    "organization_id": null
                  }
                ],
                "steps": [
                  {
                    "id": 1001,
                    "rank": 10,
                    "title": "Package tube",
                    "description": "Fill the tube",
                    "address": {
                      "label": "Home",
                      "street": "123 Fourth St",
                      "street2": "Suite 101",
                      "city": "Richmond",
                      "state": "Virginia",
                      "zip": "10001",
                      "country": "US",
                      "phone": "+17183211234",
                      "latitude": 37.5407246,
                      "longitude": -77.4360481,
                      "timezone": "America/New_York"
                    },
                    "type": "action",
                    "stage": "pre"
                  }
                ]
              }
            ]
          },
          "roles": {
            "office_user": false,
            "mobile_user": false,
            "orderer": false
          },
          "preferences": [
            {
              "id": null,
              "name": "",
              "value": null
            }
          ]
        }
      ]
    },
    "body": "",
    "type": "",
    "title": ""
  }
                    
                  

Update Note in Appointment

PUT https://api.workpath.co/appointments/[id]/notes/[noteId]

Update note in an appointment. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.

noteId number

required

Note ID.
Request Attributes

body string

Note body.

type string

Type of note.

title string

Title of note.
Request JSON
                    
  {
    "body": "Note body",
    "type": "Warning",
    "title": "Admin Note"
  }
                    
                  
Response Attributes

id number

Note ID.

author object

**PUT STUFF HERE**

body string

Body of the note.

type string

required

Type of note.

title string

Title of the note.
Note Response JSON
                    
  {
    "id": 1001,
    "author": {
      "id": 1001,
      "is_admin": false,
      "email": "user@example.com",
      "email_verified_at": "2016-09-23T18:25:43.511Z",
      "last_login_at": "2016-09-23T18:25:43.511Z",
      "tos_accepted_at": "2016-09-23T18:25:43.511Z",
      "type": [
        "Organization, Specialist"
      ],
      "latitude": 37.5407246,
      "longitude": -77.4360481,
      "gps_updated_at": null,
      "home_radius": 60,
      "location_radius": 60,
      "devices": [
        {
          "id": "nachou9e8o0e7",
          "type": "android",
          "created_at": "2019-07-01T20:45:54.000Z",
          "updated_at": "2019-07-01T20:45:54.000Z",
          "user_id": 1001
        }
      ],
      "person": {
        "id": 1001,
        "name": "Joseph Schmoseph",
        "dob": "1977-06-01",
        "gender": "female",
        "phone": "+17183211234",
        "email": "testguy@example.com",
        "photo_url": "http://example.com/pic.png",
        "addresses": [
          {
            "id": 1001,
            "label": "Home",
            "street": "123 Fourth St",
            "street2": "Suite 101",
            "city": "Richmond",
            "state": "Virginia",
            "zip": "10001",
            "country": "US",
            "phone": "+17183211234",
            "latitude": 37.5407246,
            "longitude": -77.4360481,
            "timezone": "America/New_York"
          }
        ],
        "tags": [
          {
            "id": 1001,
            "name": "Centrifuge",
            "color": "#FF0000",
            "description": "Lorem ipsum dolor sit amet",
            "locked": false,
            "alert": false,
            "organization_id": null
          }
        ],
        "documents": [
          {
            "id": 1001,
            "name": "Certification",
            "url": "https://example.com/certification"
          }
        ]
      },
      "organizations": [
        {
          "id": 1001,
          "name": "XYZ Cardiology",
          "global_id": "pgsk*a08098fad",
          "description": "Demo organization",
          "phone": "+17183211234",
          "website": "http://examplecorp.com/",
          "logo_url": "http://example.com/logo.png",
          "disable_claimed_status": false,
          "disable_available_status": false,
          "customer_contact_phone": "+17183211234",
          "customer_contact_email": "one@example.com",
          "merchant_id": null,
          "customer_id": null,
          "payment_id": null,
          "braintree_id": null,
          "prepayment_amount": 1000,
          "tiered_transactions": true,
          "users_included": 5,
          "addl_user_charge": 49.99,
          "management_fee": 0,
          "organizable": "vendor",
          "organizable_id": 1001,
          "vendor": {
            "id": 1001,
            "default_service_fee": 100,
            "default_specialist_percentage": 0,
            "organization": {
              "id": 1001,
              "name": "XYZ Cardiology",
              "description": "Demo organization",
              "phone": "+17183211234",
              "website": "http://examplecorp.com/",
              "logo_url": "http://example.com/logo.png",
              "disable_claimed_status": false,
              "disable_available_status": false,
              "customer_contact_phone": "+17183211234",
              "customer_contact_email": "one@example.com",
              "merchant_id": null,
              "customer_id": null,
              "payment_id": null,
              "braintree_id": null,
              "prepayment_amount": 1000,
              "tiered_transactions": true,
              "users_included": 5,
              "addl_user_charge": 49.99,
              "management_fee": 0,
              "organizable": "vendor",
              "organizable_id": 1001,
              "addresses": [
                {
                  "id": 1001,
                  "label": "Home",
                  "street": "123 Fourth St",
                  "street2": "Suite 101",
                  "city": "Richmond",
                  "state": "Virginia",
                  "zip": "10001",
                  "country": "US",
                  "phone": "+17183211234",
                  "latitude": 37.5407246,
                  "longitude": -77.4360481,
                  "timezone": "America/New_York"
                }
              ],
              "tags": [
                {
                  "id": 1001,
                  "name": "Centrifuge",
                  "color": "#FF0000",
                  "description": "Lorem ipsum dolor sit amet",
                  "locked": false,
                  "alert": false,
                  "organization_id": null
                }
              ],
              "preferences": [
                {
                  "id": null,
                  "name": "",
                  "value": null
                }
              ]
            },
            "services": [
              {
                "id": 1001,
                "vendor": {
                  "id": 1001
                },
                "name": "Blood Draw",
                "description": "A standard blood draw",
                "vendor_fee": 60,
                "specialist_payment": 40,
                "duration": 15,
                "shippable": false,
                "archived": false,
                "tags": [
                  {
                    "id": 1001,
                    "name": "Centrifuge",
                    "color": "#FF0000",
                    "description": "Lorem ipsum dolor sit amet",
                    "locked": false,
                    "alert": false,
                    "organization_id": null
                  }
                ],
                "steps": [
                  {
                    "id": 1001,
                    "rank": 10,
                    "title": "Package tube",
                    "description": "Fill the tube",
                    "address": {
                      "label": "Home",
                      "street": "123 Fourth St",
                      "street2": "Suite 101",
                      "city": "Richmond",
                      "state": "Virginia",
                      "zip": "10001",
                      "country": "US",
                      "phone": "+17183211234",
                      "latitude": 37.5407246,
                      "longitude": -77.4360481,
                      "timezone": "America/New_York"
                    },
                    "type": "action",
                    "stage": "pre"
                  }
                ]
              }
            ]
          },
          "roles": {
            "office_user": false,
            "mobile_user": false,
            "orderer": false
          },
          "preferences": [
            {
              "id": null,
              "name": "",
              "value": null
            }
          ]
        }
      ]
    },
    "body": "",
    "type": "",
    "title": ""
  }
                    
                  

Delete Note in Appointment

DELETE https://api.workpath.co/appointments/[id]/notes/[noteId]

Deletes a note in an appointment. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.

noteId number

required

Note ID.

Upload Document for Appointment

POST https://api.workpath.co/appointments/[id]/documents

Upload a document to an appointment.

Request Parameters

id number

required

Appointment ID.
Request Attributes

file string

required

MIME data.

name string

Title of the document. Ex: "2004 Certification"

Remove Document from Appointment

DELETE https://api.workpath.co/appointments/[id]/documents/[documentId]

Delete a document from an appointment.

Request Parameters

id number

required

Appointment ID.

documentId number

required

Document ID.

Add Data to Appointment

POST https://api.workpath.co/appointments/[id]/data

Add collected data to an appointment. Useful for storing service data, shipping IDs, etc. Requires “Update appointment details” permission.

Request Parameters

id number

required

Appointment ID.

Webhooks

Webhooks allow API users to receive notifications when events occur on appointments that were created via their Workpath integration. The webhook URL will receive a POST request containing the JSON event data.

Note These methods use HTTP Basic authentication with an API key and password. The webhook applies to all appointments created for the organization of the provided API key, regardless of the user context.

Webhook Attributes

id integer

ID of webhook

url string

URL to receive POST events

create boolean

Receive event on appointment creation

modify boolean

Receive event on appointment update

destroy boolean

Receive event on appointment deletion

secret string

The signing secret for your webhook

organization_id integer

ID of your organization
Sample Event
                    
  {
    "type": "Appointment", 
    "action": "modify",
    "eventTs": 1565712055,
    "data":{
      "id":1234,
      ...
    }
  }                                    
                    
                  

Webhook Verification

In order to ensure that your application is receiving events from Workpath and not from a third party, we include a signature in each event's WP-Signature header. To verify these signatures, you will need to note your registered webhook's secret.

The WP-Signature header contains a timestamp and a signature. The timestamp is prefixed by t= and the signature by a scheme (e.g. v1=).

Workpath generates signatures using a hash-based authentication code (HMAC) with SHA-256.

Sample Header

t=1565712055,v1=212295b0abf312cca33874fc2eedaa65a829f0bf3f26a125f19ebccfecfa1afa

Step 1: Extract the timestamp and signatures from the header

Split the header at the , character to get a list of elements. Then split each element at the = to get the prefix, value pairs. The value for the prefix t corresponds to the timestamp (also present as eventTs in the event's JSON) and v1 corresponds to the signature. Please ignore any other elements.

Step 2: Prepare a signed payload string

Get a string to sign by concatenating (into a string):

  1. The timestamp (as a string)
  2. The character .
  3. The raw JSON payload (before any parsing/formatting)
Sample Payload String

1565712055.{"type":"Appointment","action":"modify","eventTs":1565712055,...}

Step 3: Create the expected signature

Compute an HMAC with the SHA-256 hash function. Use the webhook's secret as the key and the signed payload created above as the message.

Sample Expected Signature

const secret = "NGRjNjFkMDktZjg0My00YzI1LThjOTgtZjg3NWNlZTBmOGM1" const hmac = crypto.createHmac("sha256", secret); hmac.update('{"type":"Appointment","action":"modify","eventTs":1565712055,...}'); hmac.digest("hex") === "212295b0abf312cca33874fc2eedaa65a829f0bf3f26a125f19ebccfecfa1afa"

Step 4: Compare signatures

Compare the v1 signature in the header to the expected signature. If the signature matches, the payload is valid.

To protect against replay attacks, you may also wish to compute the difference between the current timestamp and the received timestamp. We recommend a five minute tolerance between the two.


Create Webhook

POST https://api.workpath.co/webhooks

Creates a new webhook.

Request Attributes

url string

required

URL to receive POST events.

create boolean

Receive event on appointment creation.

modify boolean

Receive event on appointment update.

delete boolean

Receive event on appointment deletion.
Example Request JSON
                    
  {
    "url": "https://www.example.com/Workpathevents",
    "create": true,
    "modify": true,
    "destroy": true
  }                  
                    
                  
Response Attributes

id integer

ID of webhook

url string

URL to receive POST events

create boolean

Receive event on appointment creation

modify boolean

Receive event on appointment update

destroy boolean

Receive event on appointment deletion

secret string

The signing secret for your webhook

organization_id integer

ID of your organization
Example Response JSON
                    
  {
    "id": 1001,
    "url": "https://www.example.com/Workpathevents",
    "create": true,
    "modify": true,
    "destroy": true,
    "secret": "abcdef",
    "organization_id": 1001
  }                  
                    
                  

Update Webhook

PUT https://api.workpath.co/webhooks/[id]

Modifies an individual webhook.

Request Parameters

id number

required

Webhook ID.
Request Attributes

url string

required

URL to receive POST events.

create boolean

Receive event on appointment creation.

modify boolean

Receive event on appointment update.

delete boolean

Receive event on appointment deletion.
Example Request JSON
                    
  {
    "url": "https://www.example.com/Workpathevents",
    "create": true,
    "modify": true,
    "destroy": true
  }                  
                    
                  
Response Attributes

id integer

ID of webhook

url string

URL to receive POST events

create boolean

Receive event on appointment creation

modify boolean

Receive event on appointment update

destroy boolean

Receive event on appointment deletion

secret string

The signing secret for your webhook

organization_id integer

ID of your organization
Example Response JSON
                    
  {
    "id": 1001,
    "url": "https://www.example.com/Workpathevents",
    "create": true,
    "modify": true,
    "destroy": true,
    "secret": "abcdef",
    "organization_id": 1001
  }                  
                    
                  

Retrieve Webhook

GET https://api.workpath.co/webhooks/[id]

Retrieve details for an individual webhook.

Request Parameters

id number

required

Webhook ID.
Response Attributes

id integer

ID of webhook

url string

URL to receive POST events

create boolean

Receive event on appointment creation

modify boolean

Receive event on appointment update

destroy boolean

Receive event on appointment deletion

secret string

The signing secret for your webhook

organization_id integer

ID of your organization
Example Response JSON
                    
  {
    "id": 1001,
    "url": "https://www.example.com/Workpathevents",
    "create": true,
    "modify": true,
    "destroy": true,
    "secret": "abcdef",
    "organization_id": 1001
  }                  
                    
                  

Retrieve Webhook List

GET https://api.workpath.co/webhooks

Retrieve a list of current webhooks.

Response Attributes

id integer

ID of webhook

url string

URL to receive POST events

create boolean

Receive event on appointment creation

modify boolean

Receive event on appointment update

destroy boolean

Receive event on appointment deletion

secret string

The signing secret for your webhook

organization_id integer

ID of your organization
Example Response JSON
                    
  [
    {
      "id": 1001,
      "url": "https://www.example.com/Workpathevents",
      "create": true,
      "modify": true,
      "destroy": true,
      "secret": "abcdef",
      "organization_id": 1001
    }  
  ]
                    
                  

Delete Webhook

DELETE https://api.workpath.co/webhooks/[id]

Destroy an existing webhook.

Request Parameters

id number

required

Webhook ID.

Response from Payload

Once we receive your payload, a unique Workpath request ID will be created and sent back to you in the response. You should expect to see a JSON response similar to the following:

                    
  {
    "request_id": 12345
  }                  
                    
                  

If your request comes back to you with a status of anything other than 200 - OK, please refer to the sections below for more detailed information regarding error codes and validation messages.


Error Codes / Messaging

In the situation where you receive an error code in the response from us, you should receive a message describing the error in more detail. An example of an error would be invalid credentials or a missing field. Listed below are error codes and messages that you could receive from us. Please note that these are only error messages from the Workpath API. Generic error codes are listed at the end of this document for your reference.

HTTP Error Codes from Workpath
400 Bad Request [FIELD NAME] missing from payload.
403 Forbidden Invalid credentials.

Validation / Messaging

There are certain fields that need to be formatted in a given way in order to be processed correctly. If one of these fields is not in the correct format, you will receive a validation message from us stating one of the following things:

Error Codes with Validation Messages from Workpath
ERROR Patient DOB needs to be in the format MMDDYYYY.
ERROR [Patient] Phone Number needs to include the country code.
ERROR Invalid option selection for biological sex of patient.
ERROR Name needs to be sent as First Name and Last Name, [Last Name] is missing.
ERROR ^ cannot be used as a delimiter in payload.

Standard Errors (Auth Errors, etc.)

Below is a standard HTTP code summary for your convenience. We use conventional HTTP response codes most like other APIs.

Standard HTTP Error Codes
200 - OK Good to go!
400 - Bad Request The request was not correct - see Error Codes and Messages for details.
401 - Unauthorized Invalid credentials
402 - Request Failed Parameters were valid but the request failed.
403 - Forbidden Invalid permissions attached to credentials.
404 - Not Found Resource requested does not exist.
409 - Conflict The request conflicts with another request.
429 - Too Many Requests Too many requests hit the API at one time.
500, 502, 503, 504 - Server Errors Something went wrong on Workpath’s end.

Need additional assistance? Click Here