Ferry Health API

The Ferry Health API provides programmatic access to Appointment Tasks. Use the API to:

• Create Appointment Tasks
• Load Appointment Tasks

Authentication

To use the Ferry API, you’ll need an API key. If you don’t have one already, please reach out to get one: support@ferry.health.

In all API requests, you should provide your token using the Authorization header with the "Bearer " prefix:

1
"Authorization": "Bearer <YOUR TOKEN>"

Appointment Tasks

You can create Appointment Tasks to initiate a search for providers. See the /create-appointment-task endpoint for the available request properties.

When you create an Appointment Task, we will return an appointmentTaskId, and Ferry will asynchronously compile a list of providers with validated availability. You can poll for the status of a task using the /get-appointment-task endpoint.

Usually, a task will go through these states:

1. AWAITING_PATIENT_ENROLLMENT. When a task is created, we immediately send a text message to the patient with a link to the Ferry UI to enroll and confirm their personal details.
2. FINDING_APPOINTMENT_OPTIONS. Once the patient is enrolled, we start reaching out to providers to find the best providers for the patient’s appointment.
3. WAITING_ON_PATIENT_SELECTION. Once the best providers have been determined, we reach out to the patient via text message and ask them to choose a provider.
4. CONFIRMING_APPOINTMENT. Once the patient has selected a provider, we will reach out to the provider to confirm an appointment time.
5. APPOINTMENT_CONFIRMED. The appointment has been confirmed.

Once the task is in the WAITING_ON_PATIENT_SELECTION state, it will include some provider options:

1
{
2
  "id": "ferry.task-appointment.aa65f439-9be3-4803-bbfc-7656e337942f",
3
  "status": "WAITING_ON_PATIENT_SELECTION",
4
  "isCanceled": false,
5
  "options": [
6
    {
7
      "provider": {
8
        "npi": "1386755036",
9
        "firstName": "George",
10
        "lastName": "Griffin"
11
      },
12
      "location": {
13
        "name": "NY Family Physician Practice",
14
        "address": "102 Bedford Ave, Brooklyn, NY 11211, US"
15
      }
16
    },
17
    {
18
      "provider": {
19
        "npi": "2390110237",
20
        "firstName": "Sarah",
21
        "lastName": "Heartley"
22
      },
23
      "location": {
24
        "name": "Brooklyn Family Medicine",
25
        "address": "98 N 9th St, Brooklyn, NY 11249, US"
26
      }
27
    }
28
  ],
29
  "patient": {
30
    "id": "ferry.patient.c4d71c84-24a5-45d2-95ea-e131f9a0fa61",
31
    "firstName": "Jane",
32
    "lastName": "Smith",
33
    "address": "100 N 12th St, Brooklyn NY 11249",
34
    "phoneNumber": "+14405551234",
35
    "gender": "FEMALE",
36
    "dateOfBirth": "1980-01-31",
37
    "insurancePlanName": "Aetna - Managed Choice Open Access",
38
    "insurancePlanMemberId": "1234567890"
39
  }
40
}