Scheduler API Reference

This reference covers the four EverGrove scheduler endpoints that integrators use to manage outbound call workflows: creating entities, scheduling requests, triggering calls, and polling outcomes. All paths are relative to the base URL.

Base URL	`https://agent-api.evergrovelabs.com`
Auth	`Authorization: Bearer {API_KEY}`
Content type	`application/json`

Endpoints overview

Method	Path	Purpose
POST	`/scheduler/entities`	Create or update a scheduler entity.
POST	`/scheduler/requests`	Create queued scheduled requests.
POST	`/scheduler/trigger/v2`	Trigger one queued scheduled request.
GET	`/scheduler/requests/{requestId}`	Poll a scheduled request status and outcomes.

POST /scheduler/entities

Upserts a scheduler entity by name inside the authenticated tenant. If an entity with the same name exists, its schedule and location data are updated and the existing record is returned.

Request body

Field	Type	Required	Notes
`name`	string	Yes	Entity name (usually the provider office).
`location_name`	string \| null	No	Optional display name for the location.
`location_timezone`	string	Yes	IANA timezone (e.g. `America/New_York`).
`working_hours_policy`	object	Yes	Per-day call windows and default call time.
`ivr_answer_key_guide`	string \| null	No	Optional IVR navigation instructions.

Response body

Field	Type	Notes
`id`	string (UUID)	Entity ID to persist.
`tenant_id`	string	Authenticated tenant.
`name`	string
`location_name`	string \| null
`location_timezone`	string
`can_call`	boolean
`ivr_answer_key_guide`	string \| null
`working_hours_policy`	object
`working_hours_source`	string \| null
`working_hours_updated_at`	string \| null	ISO datetime.
`created_at`	string	ISO datetime.

Working hours policy fields

Field	Type	Notes
`<day>.default_call_time`	HH:mm \| null	Required when `windows` is present; must be inside a window.
`<day>.windows`	array	Each object has `start` and `end` (HH:mm). Omit to mark closed.

Extra fields on working-hours objects are rejected. A closed day must not set default_call_time.

POST /scheduler/requests

Queues scheduled requests.

Request body

Field	Type	Required	Notes
`calls`	array	Yes	List of `ScheduleRequestCallInput` objects.

Call input object

Field	Type	Required	Notes
`entity_id`	string (UUID)	Yes	From `POST /scheduler/entities`.
`external_reference_id`	string	Required if any call in the batch includes it	Stable caller-side ID.
`outbound_phone_number`	string	Yes	Callable NANP E.164 number.
`objective`	string	Yes	`CONFIRM_IE_ATTENDANCE` or `RESCHEDULE`.
`notes`	string \| null	No	Caller-facing notes.
`best_to_make_call_by`	ISO datetime \| null	No	Preferred deadline.
`details`	object	Yes	Patient/claim metadata.

Details object

Field	Type	Required	Notes
`organization_name`	string	Yes	Must be enabled for the tenant or scheduling returns `422`.
`patient_name`	string	Yes
`patient_ssn`	string \| null	No	9 digits, last 4, `NONE`, or `null`.
`patient_dob`	YYYY-MM-DD	Yes
`patient_phone_number`	string \| null	No	NANP phone; API normalizes to E.164.
`date_of_injury`	YYYY-MM-DD	Yes
`expected_appointment_date_time`	YYYY-MM-DDTHH:mm:ss	Yes	Timezone-naive. No offsets, `Z`, or fractional seconds.
`local_timezone`	string	Yes	IANA timezone (e.g. `America/New_York`).
`service_modality`	string	Yes
`claim_number`	string	No	Defaults to `"Not Available"` when omitted or blank.
`insurer_group_name`	string	Yes
`body_part`	string	Yes
`provider_office`	string	Yes
`provider_office_address`	string	Yes
`provider_state`	string \| null	No	US state abbreviation or full state name.
`eoc_number`	string	Yes
`details.notes`	string \| null	No	Accepted but not persisted as eval metadata.

Response body

Field	Type	Notes
`scheduled_requests`	array	List of `ScheduledRequest` objects.

Scheduled request object

Field	Type	Notes
`id`	string (UUID)	Request ID to persist and trigger.
`call_input_id`	string (UUID)
`entity_id`	string (UUID)
`external_reference_id`	string \| null
`tenant_id`	string
`workflow_status`	string	See `OutboundCallStatus` enum.
`best_to_callback_after`	ISO datetime \| null
`generated_outcomes`	object \| null	Usually null at creation.
`created_at`	string	ISO datetime.
`updated_at`	string	ISO datetime.

POST /scheduler/trigger/v2

Starts the queued call workflow for a single scheduled request.

Request body

Field	Type	Required	Notes
`scheduled_request_ids`	array	Yes	Exactly one UUID string.
`latency_mode`	`low` \| `high`	No	Defaults to `low`.

Response body

Field	Type	Notes
`triggered`	string[]	List of triggered request IDs.
`workflow_id`	string	Optional workflow reference.
`latency_mode`	`low` \| `high`
`errors`	string[]	Trigger-level errors when present.
`message`	string	Optional human-readable summary.

GET /scheduler/requests/{requestId}

Polls a request until it reaches a terminal status. Query parameters control how much detail is returned.

Path parameters

Parameter	Type	Required	Notes
`requestId`	string (UUID)	Yes	The scheduled request ID.

Query parameters

Parameter	Type	Required	Notes
`include_call_attempts`	boolean	No	Defaults to `false`. Use for debugging/auditing.

Response body

Field	Type	Notes
`id`	string (UUID)
`workflow_status`	string	See `OutboundCallStatus` enum.
`best_to_callback_after`	ISO datetime \| null
`generated_outcomes`	object \| null	See `GeneratedOutcomes` schema.
`call_attempts`	array \| undefined	Present only when `include_call_attempts=true`.
`created_at`	string	ISO datetime.
`updated_at`	string	ISO datetime.

Shared enums

OutboundCallStatus

Value	Meaning
`ENQUEUED`	Waiting to start.
`ACTIVE`	Call workflow is running.
`COMPLETE`	Finished successfully.
`ERROR`	Encountered an unrecoverable error.
`CANCELLED`	Cancelled before completion.
`DO_NOT_CALL_BACK`	Marked as do-not-call.

Generated outcomes schema

Field	Type	Notes
`called`	boolean
`time_of_call`	ISO datetime \| null
`voicemail_left`	boolean \| null
`person_spoke_with`	string \| null
`positive_or_negative_contact`	`positive` \| `negative` \| `unknown`
`original_appointment`	{ date, time } \| null
`rescheduled_appointment`	{ date, time } \| null
`additional_dates_of_service`	array of { date, time }
`appointment_attendance_status`	enum	`attended`, `canceled`, `canceled_rescheduled`, `no_show`, `no_show_rescheduled`, `unable_to_confirm`, `unknown`
`reason_why`	string \| null
`bill_sending_confirmation`	`confirmed` \| `not_confirmed` \| `not_discussed`
`report_sending_confirmation`	`confirmed` \| `not_confirmed` \| `not_discussed`

CallAttempt status values

Value	Meaning
`PLACED`	Call was placed.
`ANSWERED`	Call was answered.
`FAILED`	Call attempt failed.
`COMPLETE`	Attempt completed.
`LEGACY_COMPLETED`	Legacy completed state.

CallAttempt disposition values

Value	Meaning
`ANSWERED`	Connected with a person.
`RETRYABLE_ERROR`	Temporary failure; may be retried.
`NON_RETRYABLE_ERROR`	Permanent failure.

Common headers

Every request must include:

Authorization: Bearer {API_KEY}
Accept: application/json
Content-Type: application/json

Status notes

Terminal statuses for polling are COMPLETE, ERROR, CANCELLED, and DO_NOT_CALL_BACK. Continue polling while a request is ENQUEUED or ACTIVE, or stop when the caller's timeout policy is reached.

Was this helpful?