---
title: "Schedule Uploaded Contacts"
method: POST
path: "/api/v1/schedule-uploaded-contacts"
tags: ["scheduling"]
---

# Schedule Uploaded Contacts

`POST /api/v1/schedule-uploaded-contacts`

## Request

- Base URL: `https://api.outrival.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.outrival.com/api/v1/schedule-uploaded-contacts`
- Auth: HTTP bearer

Trigger OTTR scheduling for contacts in awaiting_scheduling status.

Without a body this processes all contacts across all campaigns that are in
'awaiting_scheduling' status, exactly as before. The optional body scopes the
run to one campaign and/or spreads the contacts over N open campaign days
instead of the next 24 hours. It uses Thompson sampling to assign optimal
next_follow_up_date_time values and transitions contacts to 'awaiting_contact'.

The scheduling process:
1. Fetches contacts in batches of 1000
2. Groups by campaign_id and timezone
3. Gets optimal hour distribution via Thompson sampling
4. Samples a specific time for each contact
5. Updates contacts to awaiting_contact status with scheduled time

Returns:
    ScheduleUploadResponse with counts and processing time

## Request body

- ScheduleUploadRequest: Optional body: scope the run to one campaign and/or spread it over open days.
  - `campaign_id` string, uuid, nullable: Only schedule this campaign's awaiting_scheduling contacts.
  - `spread_days` integer: Number of OPEN campaign days to spread the contacts over. 1 schedules within the next 24 hours (historical behaviour).

## Response `200`

Successful Response

- ScheduleUploadResponse: Response model for schedule upload endpoint.
  - `total_scheduled` integer, required
  - `total_failed` integer, required
  - `processing_time_seconds` number, required
  - `error` string, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-15** `916091692ff3`: 2 info
  - added optional request body
  - added the non-success response with the status `422`

[Operation history](https://skmtc.dev/outrival/apis/outrival-api/changes/api/v1/schedule-uploaded-contacts/post.md)

---

[API](https://skmtc.dev/outrival/apis/outrival-api.md) - [All operations](https://skmtc.dev/outrival/apis/outrival-api/llms.txt) - [OpenAPI document](https://skmtc.dev/outrival/apis/outrival-api/revisions/f27d90300b5e?raw)