Appointment Embedded

Create Appointment Task

Create an appointment task for a patient. Once you create a task, Ferry will asynchronously process the task to find providers with validated availability. You can poll for the status of the task with the [Get Appointment Task](/api-reference/appointment-embedded/get-appointment-task) endpoint. While many status transitions occur automatically, some require patient input (such as selecting a provider). When input is required, the task enters a blocked state. A blocker object is created, which prevents Ferry from proceeding until a resolution is submitted. To handle these interruptions: - Identify the issue: Retrieve active blockers with the [Get Appointment Task Blockers](/api-reference/appointment-embedded/get-appointment-task-blockers) endpoint. - Resume the task: Submit the required input using the [Resolve Appointment Task Blocker](/api-reference/appointment-embedded/resolve-appointment-task-blocker) endpoint.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
patientstring or objectRequired

Either a patient ID or a patient object.

If you supply a patient object, we will first create the patient (or update it, if a patient already exists with the provided phone number).

providerSpecialtystringRequired
The specialty of the provider that the patient needs to see.
reasonForVisitstringRequired
The reason for the patient's visit.
addressstringOptional
The address to center our search for providers. If not provided, the patient's home address will be used.
distanceInMilesdoubleOptional

The maximum distance (in miles) from the patient’s home where the provider can be located.

patientPreferencesstringOptional

Any preferences the patient has for the appointment (provider gender, age, language, etc.).

preferredProvidersobjectOptional
The practices and providers to prioritize in the search.
providerSubspecialtystringOptional
The subspecialty of the provider that the patient needs to see.
timeFramestringOptional
The time frame in which the patient needs to have the appointment. This can be in any reasonable format.
npislist of strings or list of lists of stringsOptionalDeprecated

This field is deprecated and will be removed in a future version. Use the preferredProviders field instead

The NPIs to prioritize in the search.

Response

This endpoint returns an object.
appointmentTaskIdstring

The ID of the newly created appointment task. Ferry will asynchronously process the task before it is ready for the patient to act on it. You can poll for the status of the task with the Get Appointment Task endpoint.