# Schedulable Entities Feed

Zocdoc provides a schedulable entities feed, or a file transfer containing the full list of active provider-locations in your network.

Common uses for this feed are for tuning a search algorithm to include Zocdoc availability, refreshing caches of Zocdoc data, and tracking changes to the network over time.

This same data can be accessed via the `/v1/schedulable_entities` endpoint.

## File Transfers

File uploads can be as frequent as hourly, please arrange a schedule with Zocdoc.

### SFTP

Zocdoc uploads files to an [SFTP](https://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol) server that you host. You can use:

- A managed service like [AWS Transfer Family](https://docs.aws.amazon.com/transfer/latest/userguide/create-server-sftp.html) or [Azure SFTP](https://learn.microsoft.com/en-us/azure/storage/blobs/secure-file-transfer-protocol-support).
- A third-party vendor’s hosted SFTP solution
- Or your own self-managed SFTP server


To get set up:

1. Create an SFTP user: Set up a user account on your server. You may also choose a specific directory for this user’s uploads.
2. Share connection details with Zocdoc: Host (e.g., sftp.example.com), Port (default: 22 unless customized), Username
3. Receive Zocdoc’s public key: After you share the connection details, Zocdoc will return a public key for this user. Install this key on your server to enable secure, key-based authentication for file transfers.


Files will be uploaded at the path `./upload/{year}-{month}-{day}-{hour}-{minute}-schedulable-entities.{file_extension}`.

### Cloud bucket storage

If you are interested in transfers directly to a [AWS S3](https://aws.amazon.com/s3/), [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs/), or [Google Cloud Storage](https://cloud.google.com/storage), please contact your account manager.

## Document Schema

Files can be transferred as either JSON or TSV (tab-delimited). Files will contain the list of active of provider-locations in the developer's network.

- `provider_location_id` (string): The Zocdoc provider-location ID.
- `npi` (string, optional)
- `first_name` (string)
- `last_name` (string)
- `main_specialty_id` (string): The Zocdoc specialty ID for the primary specialty of the provider.
- `default_visit_reason_id`: The default visit reason associated with the provider's main specialty.
- `video_visit` (string): `in_person` or `video_visit` location.
- `address1` (string): N/A if virtual.
- `address2` (string, optional): N/A if virtual.
- `city` (string): N/A if virtual.
- `state` (string): Always populated.
- `zip` (string): N/A if virtual.
- `accepted_insurance_plan_ids` (array of strings): A list of Zocdoc insurance plan IDs. Separated by `,` in TSV.
- `new_patient_availability.next_available_utc` (ISO-8601 timestamp, optional): The next available date and time in UTC, up to 90 days in the future, for new patients. `new_patient_next_available_utc` column in TSV.
- `new_patient_availability.next_28_days` (string): The availability status of the schedulable entity for new patients for the next 28 days (`none`, `limited`, or `available`). Limited availablility means that the entity has less than 20 timeslots available for the next 28 days. `new_patient_next_28_days` column in TSV.
- `new_patient_availability.url` (string): The GET URL to receive the schedulable entity's availability in this API for new patients for their default visit reason. `new_patient_availability_url` column in TSV.
- `existing_patient_availability.next_available_utc` (ISO-8601 timestamp, optional): The next available date and time in UTC, up to 90 days in the future, for existing patients in ISO-8601. `existing_patient_next_available_utc` column in TSV.
- `existing_patient_availability.next_28_days` (string): The availability status of the schedulable entity for existing patients for the next 28 days (`none`, `limited`, or `available`). Limited availablility means that the entity has less than 20 timeslots available for the next 28 days. `existing_patient_next_28_days` column in TSV.
- `existing_patient_availability.url` (string): The GET URL to receive the schedulable entity's availability in this API for existing patients for their default visit reason. `existing_patient_availability_url` column in TSV.
- `go_live_timestamp_utc` (ISO-8601 timestamp): The timestamp when the schedulable entity became available in the developer's directory.
- `profile_last_modified_timestamp_utc` (ISO-8601 timestamp): The timestamp when the schedulable entity's profile was last modified in the developer's directory. This includes basic information on the provider and location records.