Start Historical Sync

Creates a new historical sync job that will import past call data from the Ultravox API into the local database. The job is created in a pending state and will be picked up by the process-historical-sync cron function.

Endpoint

Property	Value
Function Name	start-historical-sync
HTTP Method	POST
Authentication	Supabase JWT (Bearer token in Authorization header)
Required Role	Any authenticated agency user

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer <supabase_jwt>
Content-Type	Yes	application/json

Body

Field	Type	Required	Description
date_from	string (ISO 8601)	No	Start of the date range to sync. If omitted, no lower bound is applied.
date_to	string (ISO 8601)	No	End of the date range to sync. Defaults to the current timestamp if omitted.

{
  "date_from": "2025-01-01T00:00:00Z",
  "date_to": "2025-03-01T00:00:00Z"
}

Response

Success (200)

{
  "job_id": "uuid-of-the-created-job",
  "status": "pending"
}

Error Responses

Status	Condition
401	Missing or invalid Authorization header / JWT token
403	Authenticated user is not associated with an agency (agency_id is null)
405	HTTP method is not POST
409	A sync job is already in progress for the agency (duplicate job conflict from create_historical_sync_job RPC)
500	Unexpected server error or RPC failure

Behavior

• Handles CORS preflight (OPTIONS) requests and rejects non-POST methods with a 405.
• Validates the JWT token via supabase.auth.getUser() to identify the caller.
• Looks up the user's agency_id and role from the users table.
• Calls the create_historical_sync_job database RPC with the agency ID and requested date range.
• If the RPC returns an error whose message includes "already exists", the function returns a 409 Conflict indicating a job is already running.
• On success, returns the newly created job ID and a pending status.

Database Tables

Table / RPC	Operation	Description
users	Read	Fetches agency_id and role for the authenticated user
create_historical_sync_job (RPC)	Write	Creates a new sync job record in historical_sync_jobs

External APIs

None. This function only creates the job record; actual Ultravox API calls happen in process-historical-sync.

Related Functions

• process-historical-sync -- Processes pending sync jobs by fetching data from Ultravox
• cancel-historical-sync -- Cancels a running or pending sync job
• get-sync-status -- Retrieves progress information for active and recent sync jobs