API Reference
API Reference

Create Outbound Communication Campaign

POST/api/v1/outbound/campaigns

Authentication

Syllable-API-Keyrequired

Send Syllable-API-Key in the header.

Need a credential? Create or manage an API token in the Syllable Console.

Parameters

This endpoint has no declared parameters.

Request body

application/json

body OutboundCampaignInput required
22 fields
campaign_namestringrequired

Human readable name of campaign

descriptionstring | nulloptional

Description of campaign

modestring | nulloptional

Mode of the campaign (e.g. voice, sms, email)

sms_session_ttlinteger | nulloptional

Time to live for SMS session in minutes

labelstring | nulloptional

Label for campaign (DEPRECATED - use labels instead)

labelsstring[] | nulloptional

Labels for campaign

Item schema
itemsstringrequired
campaign_variablesobjectrequired

Variables for campaign

1 field
{key}stringoptional
daily_start_timestring | nulloptional

Start time of campaign each day

daily_end_timestring | nulloptional

End time of campaign each day

sourcestring | nulloptional

Source phone number, email, or SMS number

caller_idstring | nullrequired

Caller ID for call

hourly_rateintegeroptional

Target number of outreach calls per hour

Default 1Minimum 1Maximum 3600
max_daily_callsinteger | nulloptional

Maximum number of outreach calls per day

retry_countintegeroptional

Number of retries per target

Default 0
retry_intervalstring | nulloptional

How long to wait before retrying

active_daysenum<string>[]required

Days of the week when campaign is active

Item schema
itemsenum<string>required

Enum representing days of the week.

Allowed values ["mon","tue","wed","thu","fri","sat","sun"]
outreach_override_rulesOutreachOverrideRules | nulloptional

Weekday- and date-specific outreach windows and daily maximums. The most specific rule wins: date, then weekday, then the campaign defaults above. Omitted or null means the campaign defaults apply to every active day.

2 options
daysobjectoptional

Rules by weekday. Full names (monday) and short names (mon) are both accepted; they are stored as short names. Days that are absent use the campaign defaults.

1 field
{key}ScheduleOverrideoptional

Outreach window and/or daily cap for one weekday or one calendar date.

Every field may be omitted, and an omitted field inherits the campaign default: an override that only sets `max_daily_calls keeps the campaign window, and one that only sets the times keeps the campaign cap. max_daily_calls: 0 is not inheritance -- it is an explicit "no outreach on this day", which is the shape the Outbound Scheduler daily_limit config already uses. It closes the day for retries as well as for first attempts, the same way active: false` does; a non-zero maximum bounds first attempts only and lets retries run on.

4 fields
activeboolean | nulloptional

Whether the campaign does outreach on this day. Omitted inherits: a weekday rule inherits from active_days, a date rule inherits from the weekday rule. Set it to false to close one date, for example a holiday, without a change to active_days.

daily_start_timestring | nulloptional

Start time on this day. Omitted keeps the campaign start time.

daily_end_timestring | nulloptional

End time on this day. Omitted keeps the campaign end time.

max_daily_callsinteger | nulloptional

Maximum number of unique reference IDs that get outreach on this day. Omitted keeps the campaign maximum. Retries do not count towards it and keep dialing once it is reached. 0 is different: it closes the day for all outreach, retries included.

Minimum 0
datesobjectoptional

Rules by calendar date, keyed YYYY-MM-DD. A date rule wins over the weekday rule for that date.

1 field
{key}ScheduleOverridereference defined above

Outreach window and/or daily cap for one weekday or one calendar date.

Every field may be omitted, and an omitted field inherits the campaign default: an override that only sets `max_daily_calls keeps the campaign window, and one that only sets the times keeps the campaign cap. max_daily_calls: 0 is not inheritance -- it is an explicit "no outreach on this day", which is the shape the Outbound Scheduler daily_limit config already uses. It closes the day for retries as well as for first attempts, the same way active: false` does; a non-zero maximum bounds first attempts only and lets retries run on.

voicemail_detectionVoicemailDetectionConfig | nulloptional

Config for voicemail detection for voice campaigns. Set to None to disable.

6 options
modeenum<string> | nulloptional

Voicemail-detection strategy: 'v1' (original check_voicemail/leave_voicemail) or 'v2' (Voicemail Detection 2, which suppresses the turn-0 greeting and uses the greeting tool). The two modes are mutually exclusive. Omitted/null on legacy v1 campaigns is treated as v1.

Allowed values ["v1","v2"]
voicemail_detection_overall_timeoutnumber | nulloptional
voicemail_detection_pre_speech_timeoutnumber | nulloptional
voicemail_detection_post_speech_timeoutnumber | nulloptional
voicemail_detection_speech_thresholdnumber | nulloptional
voicemail_detection_v2_pre_speech_timeoutnumber | nulloptional
allowed_line_typesenum<string>[] | nulloptional

Line-type buckets this campaign is allowed to dial. Empty or omitted means no filter (all line types are dialed).

Item schema
itemsenum<string>required

Friendly line-type buckets a campaign can be restricted to dial.

These map to raw Twilio Lookup v2 line types via `lib.twilio.line_type_lookup.LINE_TYPE_BUCKETS`.

Allowed values ["mobile","landline","voip"]
include_unknown_line_typesbooleanoptional

When a line-type filter is active, whether to also dial numbers whose line type is unknown or could not be classified. Has no effect when allowed_line_types is empty.

Default true
target_filtersTargetFilters | nulloptional

Generic target filter (a flat rule list over request enrichment attributes such as line_type, caller_type, caller_name, carrier_name, mcc, mnc). When set, takes precedence over allowed_line_types / include_unknown_line_types. Omitted or null means those legacy fields are used instead. Rules on caller_type / caller_name are resolved by Twilio's separately billed caller_name (CNAM) lookup, which only returns data for US numbers.

3 options
matchenum<string>optional

How to combine rules: 'all' (AND) or 'any' (OR).

Allowed values ["all","any"]Default all
on_unknownenum<string>optional

Whether to dial requests whose enrichment is unresolved (no lookup data). Applied per rule: it decides what a rule contributes when that rule's attribute is unresolved, and never overrides a rule the request definitively failed -- so a request that fails one rule is still skipped even if a different rule's attribute is missing. "Unresolved" covers a missing value and also the value Twilio returns to mean "looked up, could not answer": for line_type that is 'unknown' (a valid number whose line type it could not determine), and for caller_type both no CNAM data at all (non-US numbers) and 'UNDETERMINED' (a US number it looked up but could not classify).

Allowed values ["include","exclude"]Default include
rulesTargetFilterRule[]optional

Predicates over request enrichment attributes. Empty means no filter.

Item schema
itemsTargetFilterRulerequired

A single predicate over one enrichment attribute of an outbound request.

`field names a key in the request's enrichment payload (e.g. line_type, caller_type, caller_name, carrier_name, mcc, mnc`). Any attribute captured at lookup time can be filtered on with no code change.

Which Twilio Lookup data packages get requested (and billed) for a campaign is derived from the fields its rules reference, so a rule on `caller_type / caller_name is what turns on the separately billed caller_name` package.

3 fields
fieldstringrequired

Enrichment attribute to match on (a key in the request enrichment payload).

openum<string>required

Comparison operator.

Allowed values ["in","not_in","eq","neq","exists","not_exists"]
valuesstring[]optional

Values to compare against. Ignored for exists / not_exists.

Item schema
itemsstringrequired
webhooksOutboundCampaignWebhookInput[]optional

Webhooks for campaign

Default []
Item schema
itemsOutboundCampaignWebhookInputrequired
5 fields
trigger_statusesenum<string>[]required

Condition expression evaluated when the trigger fires

Item schema
itemsenum<string>required

Status of an outbound communication request (voice, SMS, or email).

Allowed values ["PENDING","DUPLICATE","INVALID","UNEXPECTED_ERROR","FILTERED_LINE_TYPE","NO_OUTCOME","PROCESSED","DROPPED","DEFERRED","BOUNCED","DELIVERED","OPENED","CLICKED","SPAM_REPORT","UNSUBSCRIBED","PRIOR_UNSUBSCRIBED","PRIOR_SPAM_REPORT","PRIOR_DROPPED","PRIOR_BOUNCED","SENT","ACCEPTED","QUEUED","SENDING","UNDELIVERED","DELIVERY_UNKNOWN","DELIVERY_FAILED","IN-PROGRESS","BUSY","CANCELED","COMPLETED","DECLINED","NO-ANSWER","MACHINE","HUMAN","UNKNOWN","FAILED","SIP_NOT_FOUND","SIP_TEMPORARILY_UNAVAILABLE","SIP_LOOP_DETECTED","SIP_DOES_NOT_EXIST_ANYWHERE"]
urlstringrequired

HTTPS URL to which to send the webhook payload

request_methodstringrequired

HTTP method for the outbound request (POST, PUT, or PATCH)

idinteger | nulloptional

Unique ID for webhook, if updating an existing webhook

auth_valuesobject | nulloptional

Optional dict of auth values. Currently, only the key "hmac_secret" is allowed; value must be standard Base64 (RFC 4648) decoding to 32–512 bytes of key material. On update, leave a value for a given key null and the stored value for that key is kept. (If a key is omitted entirely, any existing value for that key is removed.)

1 options
{key}string | nulloptional
Request example
{
  "campaign_name": "string",
  "description": "string",
  "mode": "string",
  "sms_session_ttl": "string",
  "label": "string",
  "labels": "string",
  "campaign_variables": "string",
  "daily_start_time": "string",
  "daily_end_time": "string",
  "source": "string",
  "caller_id": "string",
  "hourly_rate": 1,
  "max_daily_calls": "string",
  "retry_count": 0,
  "retry_interval": "string",
  "active_days": [
    "string"
  ],
  "outreach_override_rules": "string",
  "voicemail_detection": "string",
  "allowed_line_types": "string",
  "include_unknown_line_types": true,
  "target_filters": "string",
  "webhooks": []
}

Responses

200Successful Response

application/json

response OutboundCampaign | null required
27 options
campaign_namestringrequired

Human readable name of campaign

descriptionstring | nulloptional

Description of campaign

modestring | nulloptional

Mode of the campaign (e.g. voice, sms, email)

sms_session_ttlinteger | nulloptional

Time to live for SMS session in minutes

labelstring | nulloptional

Label for campaign (DEPRECATED - use labels instead)

labelsstring[] | nulloptional

Labels for campaign

Item schema
itemsstringrequired
campaign_variablesobjectrequired

Variables for campaign

1 field
{key}stringoptional
daily_start_timestring | nulloptional

Start time of campaign each day

daily_end_timestring | nulloptional

End time of campaign each day

sourcestring | nulloptional

Source phone number, email, or SMS number

caller_idstring | nullrequired

Caller ID for call

hourly_rateintegeroptional

Target number of outreach calls per hour

Default 1Minimum 1Maximum 3600
max_daily_callsinteger | nulloptional

Maximum number of outreach calls per day

retry_countintegeroptional

Number of retries per target

Default 0
retry_intervalstring | nulloptional

How long to wait before retrying

active_daysenum<string>[]required

Days of the week when campaign is active

Item schema
itemsenum<string>required

Enum representing days of the week.

Allowed values ["mon","tue","wed","thu","fri","sat","sun"]
outreach_override_rulesOutreachOverrideRules | nulloptional

Weekday- and date-specific outreach windows and daily maximums. The most specific rule wins: date, then weekday, then the campaign defaults above. Omitted or null means the campaign defaults apply to every active day.

2 options
daysobjectoptional

Rules by weekday. Full names (monday) and short names (mon) are both accepted; they are stored as short names. Days that are absent use the campaign defaults.

1 field
{key}ScheduleOverrideoptional

Outreach window and/or daily cap for one weekday or one calendar date.

Every field may be omitted, and an omitted field inherits the campaign default: an override that only sets `max_daily_calls keeps the campaign window, and one that only sets the times keeps the campaign cap. max_daily_calls: 0 is not inheritance -- it is an explicit "no outreach on this day", which is the shape the Outbound Scheduler daily_limit config already uses. It closes the day for retries as well as for first attempts, the same way active: false` does; a non-zero maximum bounds first attempts only and lets retries run on.

4 fields
activeboolean | nulloptional

Whether the campaign does outreach on this day. Omitted inherits: a weekday rule inherits from active_days, a date rule inherits from the weekday rule. Set it to false to close one date, for example a holiday, without a change to active_days.

daily_start_timestring | nulloptional

Start time on this day. Omitted keeps the campaign start time.

daily_end_timestring | nulloptional

End time on this day. Omitted keeps the campaign end time.

max_daily_callsinteger | nulloptional

Maximum number of unique reference IDs that get outreach on this day. Omitted keeps the campaign maximum. Retries do not count towards it and keep dialing once it is reached. 0 is different: it closes the day for all outreach, retries included.

Minimum 0
datesobjectoptional

Rules by calendar date, keyed YYYY-MM-DD. A date rule wins over the weekday rule for that date.

1 field
{key}ScheduleOverridereference defined above

Outreach window and/or daily cap for one weekday or one calendar date.

Every field may be omitted, and an omitted field inherits the campaign default: an override that only sets `max_daily_calls keeps the campaign window, and one that only sets the times keeps the campaign cap. max_daily_calls: 0 is not inheritance -- it is an explicit "no outreach on this day", which is the shape the Outbound Scheduler daily_limit config already uses. It closes the day for retries as well as for first attempts, the same way active: false` does; a non-zero maximum bounds first attempts only and lets retries run on.

voicemail_detectionVoicemailDetectionConfig | nulloptional

Config for voicemail detection for voice campaigns. Set to None to disable.

6 options
modeenum<string> | nulloptional

Voicemail-detection strategy: 'v1' (original check_voicemail/leave_voicemail) or 'v2' (Voicemail Detection 2, which suppresses the turn-0 greeting and uses the greeting tool). The two modes are mutually exclusive. Omitted/null on legacy v1 campaigns is treated as v1.

Allowed values ["v1","v2"]
voicemail_detection_overall_timeoutnumber | nulloptional
voicemail_detection_pre_speech_timeoutnumber | nulloptional
voicemail_detection_post_speech_timeoutnumber | nulloptional
voicemail_detection_speech_thresholdnumber | nulloptional
voicemail_detection_v2_pre_speech_timeoutnumber | nulloptional
allowed_line_typesenum<string>[] | nulloptional

Line-type buckets this campaign is allowed to dial. Empty or omitted means no filter (all line types are dialed).

Item schema
itemsenum<string>required

Friendly line-type buckets a campaign can be restricted to dial.

These map to raw Twilio Lookup v2 line types via `lib.twilio.line_type_lookup.LINE_TYPE_BUCKETS`.

Allowed values ["mobile","landline","voip"]
include_unknown_line_typesbooleanoptional

When a line-type filter is active, whether to also dial numbers whose line type is unknown or could not be classified. Has no effect when allowed_line_types is empty.

Default true
target_filtersTargetFilters | nulloptional

Generic target filter (a flat rule list over request enrichment attributes such as line_type, caller_type, caller_name, carrier_name, mcc, mnc). When set, takes precedence over allowed_line_types / include_unknown_line_types. Omitted or null means those legacy fields are used instead. Rules on caller_type / caller_name are resolved by Twilio's separately billed caller_name (CNAM) lookup, which only returns data for US numbers.

3 options
matchenum<string>optional

How to combine rules: 'all' (AND) or 'any' (OR).

Allowed values ["all","any"]Default all
on_unknownenum<string>optional

Whether to dial requests whose enrichment is unresolved (no lookup data). Applied per rule: it decides what a rule contributes when that rule's attribute is unresolved, and never overrides a rule the request definitively failed -- so a request that fails one rule is still skipped even if a different rule's attribute is missing. "Unresolved" covers a missing value and also the value Twilio returns to mean "looked up, could not answer": for line_type that is 'unknown' (a valid number whose line type it could not determine), and for caller_type both no CNAM data at all (non-US numbers) and 'UNDETERMINED' (a US number it looked up but could not classify).

Allowed values ["include","exclude"]Default include
rulesTargetFilterRule[]optional

Predicates over request enrichment attributes. Empty means no filter.

Item schema
itemsTargetFilterRulerequired

A single predicate over one enrichment attribute of an outbound request.

`field names a key in the request's enrichment payload (e.g. line_type, caller_type, caller_name, carrier_name, mcc, mnc`). Any attribute captured at lookup time can be filtered on with no code change.

Which Twilio Lookup data packages get requested (and billed) for a campaign is derived from the fields its rules reference, so a rule on `caller_type / caller_name is what turns on the separately billed caller_name` package.

3 fields
fieldstringrequired

Enrichment attribute to match on (a key in the request enrichment payload).

openum<string>required

Comparison operator.

Allowed values ["in","not_in","eq","neq","exists","not_exists"]
valuesstring[]optional

Values to compare against. Ignored for exists / not_exists.

Item schema
itemsstringrequired
idintegerrequired

Unique ID for campaign

agent_idinteger | nulloptional

ID of agent assigned to campaign

created_atstring (date-time)optional

Timestamp of campaign creation

updated_atstring (date-time)optional

Timestamp of campaign update

last_updated_bystringrequired

Email of user who last updated campaign

webhooksOutboundCampaignWebhookResponse[] | nulloptional

Webhooks for campaign

Item schema
itemsOutboundCampaignWebhookResponserequired
5 fields
trigger_statusesenum<string>[]required

Condition expression evaluated when the trigger fires

Item schema
itemsenum<string>required

Status of an outbound communication request (voice, SMS, or email).

Allowed values ["PENDING","DUPLICATE","INVALID","UNEXPECTED_ERROR","FILTERED_LINE_TYPE","NO_OUTCOME","PROCESSED","DROPPED","DEFERRED","BOUNCED","DELIVERED","OPENED","CLICKED","SPAM_REPORT","UNSUBSCRIBED","PRIOR_UNSUBSCRIBED","PRIOR_SPAM_REPORT","PRIOR_DROPPED","PRIOR_BOUNCED","SENT","ACCEPTED","QUEUED","SENDING","UNDELIVERED","DELIVERY_UNKNOWN","DELIVERY_FAILED","IN-PROGRESS","BUSY","CANCELED","COMPLETED","DECLINED","NO-ANSWER","MACHINE","HUMAN","UNKNOWN","FAILED","SIP_NOT_FOUND","SIP_TEMPORARILY_UNAVAILABLE","SIP_LOOP_DETECTED","SIP_DOES_NOT_EXIST_ANYWHERE"]
urlstringrequired

HTTPS URL to which to send the webhook payload

request_methodstringrequired

HTTP method for the outbound request (POST, PUT, or PATCH)

idintegerrequired

Unique ID for webhook

auth_value_keysstring[] | nulloptional

Auth value keys (values omitted for security); only hmac_secret is currently supported

Item schema
itemsstringrequired
Response example
string
422Validation Error

application/json

response HTTPValidationError required
1 field
detailValidationError[]optional
Item schema
itemsValidationErrorrequired
3 fields
locstring | integer[]required
Item schema
itemsstring | integerrequired
2 options
Option 1stringrequired
Option 2integerrequired
msgstringrequired
typestringrequired
Response example
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}