Skip to main content
Request and manage individual calls with retry strategies.
Base path: /call-requests

​
Types

// ============================================
// 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';
}

​
Request an ad-hoc call

Immediate execution: 
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: 
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
With fixed-delay retry: 
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: 
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
Scheduled start: 
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: 
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
Scheduled retry dates: 
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: 
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}
Error Responses:
CodeErrorDescription
400CallRequestValidationErrorInvalid request (missing fields, invalid format)
400InvalidRetryStrategyErrorMalformed retry strategy
400InvalidStartTimeErrorstartAt is in the past
404FlowNotFoundErrorFlow does not exist
404DidNotFoundErrorDID not found
400DidNotActiveErrorDID is not active
400DidNotAccessibleErrorDID is not available to this organization
404ContactNotFoundErrorContact 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.