> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomobile.ma/llms.txt
> Use this file to discover all available pages before exploring further.

# Ad-hoc Calls

> Make individual calls outside of campaigns

Request and manage individual calls with retry strategies.

<Info>
  **Base path: `/call-requests`**
</Info>

***

## Types

<Accordion title="Type Definitions">
  ```typescript theme={null}
  // ============================================
  // RETRY STRATEGY
  // ============================================

  type RetryStrategy =
    | { type: 'none' }
    | { type: 'fixed-delay'; delay: number; maxRetries: number }  // delay in ms
    | { type: 'scheduled'; dates: string[] };  // ISO date strings

  // ============================================
  // REQUEST TYPES
  // ============================================

  interface RequestCallDto {
    /** DID UUID for outbound caller ID (from GET /dids/available) */
    didId: string;

    /** Contact being called (phone fetched from contact.primaryPhone) */
    contactId: string;

    /** Flow to execute during call */
    flowId: string;

    /** Retry strategy */
    retry: RetryStrategy;

    /** Optional: Schedule call for future execution (ISO date string) */
    startAt?: string;
  }

  // ============================================
  // RESPONSE TYPES
  // ============================================

  interface CallRequestResult {
    /** UUID job ID for tracking and querying reports */
    jobId: string;

    /** Always 'queued' (execution happens async) */
    status: 'queued';
  }
  ```
</Accordion>

***

### Request an ad-hoc call

Immediate execution:

```bash theme={null}
curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": { "type": "none" }
}
'
```

Response:

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
```

With fixed-delay retry:

```bash theme={null}
curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": {
    "type": "fixed-delay",
    "delay": 300000,
    "maxRetries": 3
  }
}
'
```

Response:

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
```

Scheduled start:

```bash theme={null}
curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": { "type": "none" },
  "startAt": "2025-12-17T10:00:00Z"
}
'
```

Response:

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
```

Scheduled retry dates:

```bash theme={null}
curl -X POST https://api.gomobile.ma/api/call-requests \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "didId": "123e4567-e89b-12d3-a456-426614174000",
  "contactId": "contact_123",
  "flowId": "flow_789",
  "retry": {
    "type": "scheduled",
    "dates": [
      "2025-12-17T11:00:00Z",
      "2025-12-17T14:00:00Z"
    ]
  }
}
'
```

Response:

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
```

**Error Responses:**

| Code | Error                        | Description                                      |
| ---- | ---------------------------- | ------------------------------------------------ |
| 400  | `CallRequestValidationError` | Invalid request (missing fields, invalid format) |
| 400  | `InvalidRetryStrategyError`  | Malformed retry strategy                         |
| 400  | `InvalidStartTimeError`      | startAt is in the past                           |
| 404  | `FlowNotFoundError`          | Flow does not exist                              |
| 404  | `DidNotFoundError`           | DID not found                                    |
| 400  | `DidNotActiveError`          | DID is not active                                |
| 400  | `DidNotAccessibleError`      | DID is not available to this organization        |
| 404  | `ContactNotFoundError`       | Contact does not exist or has no phone           |

***

### Cancel a queued call

**Notes:**

* No-op if call is already executing or completed
* Only cancels calls in `waiting` or `delayed` state

```
DELETE /call-requests/550e8400-e29b-41d4-a716-446655440000
// Response 204 (no body)
```

***

## Notes

* `organizationId` is automatically injected from the authenticated user's organization
* Phone number is fetched from `contact.primaryPhone`. Caller ID is resolved from the DID UUID via `GET /dids/available`
* `jobId` is a UUID that can be used to query reports via `/call-report/:jobId`
* Priority is fixed at `3` for ad-hoc calls (configurable for program calls)
* **Program calls vs ad-hoc calls:** This API is for ad-hoc (manual) calls. Program calls are initiated by the Program Orchestrator internally with `retry: { type: 'none' }` - the orchestrator manages retries externally via `execution_contacts` table to respect capacity limits and pause windows.