Create a call campaign

Prepare an outbound call campaign for a voice Agent with up to 10000 recipients, each a phone address with an optional contactId, variables, firstMessage and instructions. Nobody is called until it is started. Each recipient's contact is the one it names, or the owner of its number (created when none exists). Calls happen only inside contactHours (in timeZone, the organization's by default) and between scheduledStartAt and scheduledEndAt; each recipient gets up to maxAttempts calls, retried retryAfterMinutes later after the results in retryOn (no_answer, failure). Starting it (REST POST /v1/campaigns/{campaignId}/start) is not an AI tool.

Scope: raiz:campaigns:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; not idempotent: check the outcome before you retry
Limits: request body up to 2 MB, response up to 1 MB
CLI: arbol raiz campaigns create · MCP tool: raiz_campaigns_create

POST

https://api.getarbol.com/v1/raiz/campaigns

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope raiz:campaigns:write. Get an API key.

Request body JSON required

agentId
string
required
Agent id.

pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
name
string
required
maxLength: 200 · minLength: 1
channelId
optional
string | null
Channel id.

pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
contactHours
optional
array of
object
When calls may start, in the campaign's time zone. Empty: any time.
- days
  array of
  MO
  or
  TU
  or
  WE
  or
  TH
  or
  FR
  or
  SA
  +1 more
  required
- from
  string
  required
  Local start time, HH:MM, inclusive.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
- to
  string
  required
  Local end time, HH:MM, exclusive (24:00 for midnight).
  
  pattern: ^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$
}
firstMessage
optional
string | null
What the Agent says first on every call. Null: the Agent's own first message.

maxLength: 2000 · minLength: 1
instructions
optional
string | null
What these calls are about, added to the Agent's instructions on every call.

maxLength: 8000 · minLength: 1
maxAttempts
optional
integer
Calls per recipient at most, retries included. Default 1.

maximum: 10 · minimum: 1
metadata
optional
object
Your own keys and labels for this resource (up to 50 keys of 40 characters; values up to 500 characters). Raíz never interprets them.
retryAfterMinutes
optional
integer
Wait before a retry. Default 60.

maximum: 10080 · minimum: 1
retryOn
optional
array of
no_answer
or
failure
Which results earn a retry. Default ["no_answer"].
scheduledEndAt
optional
string | null
No call starts after this instant.

format: date-time
scheduledStartAt
optional
string | null
No call starts before this instant, even once the campaign is started.

format: date-time
timeZone
optional
string
IANA time zone name.

maxLength: 64 · pattern: ^[A-Za-z]+(/[A-Za-z0-9_+-]+)*$
recipients
optional
array of
object
Who to call, unique by address. A recipient's contact is contactId, or else the contact that owns its number (created when the organization has none).
- address
  string
  required
  Phone number in E.164 format.
  
  pattern: ^\+[1-9][0-9]{1,14}$
- contactId
  optional
  string
  The contact the call is about. Omitted: the contact that owns address, created when the organization has none.
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- firstMessage
  optional
  string | null
  What the Agent says first to this recipient, instead of the campaign's.
  
  maxLength: 2000 · minLength: 1
- instructions
  optional
  string | null
  Extra instructions for this call, after the campaign's.
  
  maxLength: 8000 · minLength: 1
- variables
  optional
  object
  Values for the {{name}} variables the Agent's instructions, first message or this campaign's texts reference. Raíz always provides contact_name, contact_given_name, contact_id, contact_phone, conversation_id and bulletins (the business bulletins in force), which a recipient's values never replace.
}

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- agentId
  string
  required
  Agent id.
  
  pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- channelId
  string | null
  required
  The voice line calls leave from. Null: the Agent's own outbound line.
  
  pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- contactHours
  array of
  object
  required
  When calls may start, in the campaign's time zone. Empty: any time.
  
  days
  array of
  MO
  or
  TU
  or
  WE
  or
  TH
  or
  FR
  or
  SA
  +1 more
  required
  from
  string
  required
  Local start time, HH:MM, inclusive.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  to
  string
  required
  Local end time, HH:MM, exclusive (24:00 for midnight).
  
  pattern: ^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$
- createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- endedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- firstMessage
  string | null
  required
- id
  string
  required
  Campaign id.
  
  pattern: ^cmp_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- instructions
  string | null
  required
- maxAttempts
  integer
  required
  maximum: 10 · minimum: 1
- metadata
  object
  required
  Your own keys and labels for this resource (up to 50 keys of 40 characters; values up to 500 characters). Raíz never interprets them.
- name
  string
  required
- progress
  object
  required
  How many recipients are in each state.
  
  completed
  integer
  required
  minimum: 0
  failed
  integer
  required
  minimum: 0
  inProgress
  integer
  required
  minimum: 0
  pending
  integer
  required
  minimum: 0
  recipients
  integer
  required
  minimum: 0
  succeeded
  integer
  required
  Recipients whose latest call's analysis judged it successful.
  
  minimum: 0
- retryAfterMinutes
  integer
  required
  minimum: 1
- retryOn
  array of
  no_answer
  or
  failure
  required
- scheduledEndAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- scheduledStartAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- startedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- status
  queued
  or
  running
  or
  paused
  or
  completed
  or
  cancelled
  or
  failed
  required
  queued: not started yet (or its start is scheduled). running: calling due recipients. paused: started, then paused; calls in progress finish. completed: no recipient is left to call.
- timeZone
  string
  required
- updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- version
  integer
  required
  minimum: 1
- recipients
  optional
  object
  The campaign's recipients in the order they were added, each with its latest attempt. Present only when expanded.
  
  data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  address
  string
  required
  attemptCount
  integer
  required
  minimum: 0
  contactId
  string | null
  required
  Contact id.
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  errorCode
  string | null
  required
  Why the recipient failed: NO_ANSWER or CALL_FAILED after its last attempt, CONTACT_SUPPRESSED when a suppression rule forbids the number.
  
  firstMessage
  string | null
  required
  id
  string
  required
  Campaign recipient id.
  
  pattern: ^rcp_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  instructions
  string | null
  required
  lastAttempt
  object | null
  required
  The latest call to this recipient; its transcript is getConversation.
  
  conversationId
  string
  required
  Conversation id.
  
  pattern: ^cnv_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  outcome
  success
  or
  failure
  or
  unknown
  or
  null
  required
  startedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  status
  open
  or
  closed
  required
  nextAttemptAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  status
  pending
  or
  in_progress
  or
  completed
  or
  failed
  or
  cancelled
  required
  pending: waiting for its (next) call. in_progress: being called. completed: an attempt succeeded. failed: its attempts ran out, or it cannot be called.
  
  updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  variables
  object
  required
  Values for the {{name}} variables the Agent's instructions, first message or this campaign's texts reference. Raíz always provides contact_name, contact_given_name, contact_id, contact_phone, conversation_id and bulletins (the business bulletins in force), which a recipient's values never replace.
  
  object
  string
  required
  Discriminator for a resource list response.
  
  pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.
INVALID_CURSOR: The cursor is malformed or belongs to a different list.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

409

VOICE_AGENT_NOT_READY: The Agent cannot take calls yet: it must be an active voice Agent with instructions, published for calls.
INVALID_STATE: The resource is not in a state that allows this operation.
VERSION_CONFLICT: The resource changed after it was read. Read it again and retry with the new version.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

422

TIME_ZONE_UNKNOWN: The time zone is not in the IANA time zone database.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}