API Reference

Create Sequence Contacts

post
https://api.whippy.co/v1/sequences//contacts

Adds contacts to the sequence in the specified step.

Send to or included_audience, not both. to is a list of phone numbers or emails.
A new contact is created when no contact in the organization matches an entry in to.
included_audience is a list of Whippy Query filter items, the same item shape as the filter
array on the public contact filter. It selects contacts that already exist and does not create contacts. custom_data
and voice_options apply only to to. When included_audience is used and the step already
has a channel, that channel is the sender. A different from is rejected, and a disabled step channel
is rejected.

If a new contact is created, it also creates a new conversation with the from number or email channel or the step's location (if any) when provided.
If there is an existing contact but no conversation, a new conversation will be created.

If there is more than one contact in the to list, the contacts will be tagged with an upload tag with a timestamp corresponding to the time of the request.

If contact is already in the specified sequence step it will be reprocessed and if it is active or pending in another step of the sequence it will be ignored.
Besides that, if contact is already in the sequence its up to the sequence settings if the contact will be added again or ignored.

If the contacts in the list do not contain the necessary contact information in the list, they will be ignored.
For example, if adding contacts to an email sequence, we will only add the contacts with an email address.
Contacts with invalid email addresses will be ignored.

For fax steps, use a fax channel as from and ensure each contact has a phone number (the fax destination).

When custom_data is provided, the contacts will be associated with a custom object. The custom object and its custom properties must be created before the contacts are added to the sequence. When specifying custom data, the resource field must be set to contact or step_contact in order to associate the custom data with the contact or the step contact respectively.

When voice_options is provided, the contacts will be added to the step with them. It will be used to answer inbound calls from the contacts that are a response to a sequence message.
If provided, it takes priority over the sequence settings default call flow ID.

The process will run in the background, therefore a 202 Accepted status is initially returned on success.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

Sequence ID

Body Params

Create Sequence Contacts Params

Request schema for adding contacts to a sequence.

Provide to or included_audience, not both. to creates a contact when none matches.
included_audience enrolls contacts that already exist and does not create contacts.
custom_data and voice_options apply only when to is sent.

custom_data
object

Optional field used to indicate that the contacts from the to list should be associated with a custom object. In combination with the custom_data field, there should be a properties field for each item in the to list, that contains the actual custom data to be associated with the contacts.

string

Phone number or email address of an existing channel in your organization. Must match the step's channel type (for example, a fax channel number for a fax step).

included_audience
array of objects
length ≥ 1

The existing contacts to enroll. Each item uses the same fields as an item in the filter
array of POST /v1/contacts/filter. An empty list is rejected.

This selects contacts already in the organization. It does not create contacts.

SequenceIncludedAudience
and
array of objects
length ≥ 0

List of filter items that should be compared to the current item using AND logic.
The logic is as follows (current_item AND (first_and_item and second_and_item and ...)).
Each filter item also supports the or key, so you can nest and and or items and build complex logic like (current_item and (first_and_item or (first_nested_or_item))).

and
cast
object

Cast the value from one type to another

string
required

The column on the resource on which the comparison should be executed

string
enum
required

The comparison operator to use

boolean

When true, keep only records that have a matching related row. When false, keep records with no match. Omit to left-join. Set true for tag, list, segment, and custom-object filters.

on
array of objects
length ≥ 0

List of on items that should be used to join parent resource with child resource.
The logic is as follows (parent_resource JOIN child_resource ON parent_resource.parent_column = child_resource.child_column).

on
or
array of objects
length ≥ 0

List of filter items that should be compared to the current item using OR logic.
The logic is as follows (current_item or (first_or_item and second_or_item and ...)).
Each filter item also supports the or key, so you can nest or items and build complex logic like (current_item or (first_or_item or (first_nested_or_item))).

or
string
required

On which resource the filter should be applied. Accepts either one of the built-in Whippy resources (campaign, campaign_contact, campaign_message, communication_preference, contact, contact_message, conversation, join_custom_data, list, message, segment, sequence_run, step_contact, tag) or the key of any custom object defined in your organization.

string
required

Bare JSON only — never {} or {"value"|"values"|"scalar": ...}. ==/!=/</>/<=/>=/like/ilike/… → string, number, or boolean (e.g. "Placed", true, 50000). in/not_in/ilike_any/not_ilike_all/between → JSON array. in_radius/not_in_radius → [lng, lat, meters]. contains/not_contains/is_contained → non-empty object or homogeneous array only.

string

Explicit join path from the contact to this custom-object row: owner>hop>hop…
(e.g. staffing_placement>candidate_placement or staffing_placement>candidate_placement>job).

Use when list_custom_objects shows more than one whippy/custom association that could
reach the same type — otherwise the engine may pick another route and return the wrong
people (candidate vs recruiter on the same placement). Named whippy_association →
type_key>name; unnamed → type_key>source_property_key. Nested and children that must
hold on the SAME related row must share or extend this via. Omit for built-ins and for
types with a single unambiguous contact link.

date-time

Scheduling time for the sequence contacts activation. Requires ISO 8601 format.

string

ID of an existing step of the sequence.

Defaults to the first step of the sequence.

to
array of objects
length between 1 and 4000

List of contacts that would be added to the sequence. Creates contacts that do not already exist.

to

Data for a contact that would be added to the sequence.

address
object

Optional Address details of the Contact

birth_date
object

Birthday details of the Contact.

uuid

The ID of the channel from which the contact should receive messages by default.

string
length ≤ 255

Contact email

string

The external ID of a contact. It uniquely identifies a contact and
can be useful for associating whippy contacts with external systems.

string

The language preference of the Contact

string
length ≤ 255

Contact name

boolean

Whether the contact is opted in to email at the organization level

boolean

Whether the contact is opted in to SMS at the organization level

boolean

Whether the contact is opted out of all organization-level channel types

string
required

Contact phone number

properties
object

Contact properties mapped to custom data. These properties are mapped to the custom object in the payload.

The properties keys should correspond to the keys of the custom properties that belong to the custom object.

voice_options
object

Optional field used to indicate the default call flow id to use for answering inbound calls from the contacts that are a response to a sequence message

Responses

Callback

Updated 8 days ago

Did this page help you?
Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 8 days ago

Did this page help you?