Menu

Create Segment

The Segmentation V2 API is in public beta. V2 segments can now be created and edited through both the UI and API.

You can see both V1 and V2 segments you have created with their contacts in the UI. While the UI only supports creation of V2 segments, you can still edit or delete either V1 or V2 segments in the UI. Both V1 and V2 segments can be exported and used as an audience for a Single Send or Automation. See the V2 Segmentation API documentation for more information.

POST /marketing/segments/2.0

Segment name has to be unique. A user can not create a new segment with an existing segment name.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Request Body

object
name
string

Name of the segment.

maxLength: 100minLength: 1
required
parent_list_ids
array[string]

The array of list ids to filter contacts on when building this segment. It allows only one such list id for now. We will support more in future

uniqueItems: True
query_dsl
string

SQL query which will filter contacts based on the conditions provided

required

Responses

object
id
string

ID assigned to the segment when created.

format: uuidmaxLength: 36minLength: 36
required
name
string

Name of the segment.

maxLength: 100minLength: 1
required
query_dsl
string

SQL query which will filter contacts based on the conditions provided

required
contacts_count
integer

Total number of contacts present in the segment

required
contacts_sample
array[object]

A subset of all contacts that are in this segment

required
id
string

ID assigned to a contact when added to the system.

format: uuidmaxLength: 36pattern: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}
email
string

Email of the contact. This is a reserved field.

format: emailmaxLength: 254minLength: 3
alternate_emails
array[string]

Alternate emails of the contact. This is a reserved field.

minItems: 0uniqueItems: True
first_name
string

First name of the contact. This is a reserved field.

minLength: 1
last_name
string

Last name of the contact. This is a reserved field.

minLength: 1
address_line_1
string

First line of address of the contact. This is a reserved field.

minLength: 0
address_line_2
string

Second line of address of the contact. This is a reserved field.

minLength: 0
city
string

City associated with the contact. This is a reserved field.

minLength: 0pattern: ^[a-zA-Z\u0080-\u024F\s\/\-\)\(\`\.\"\']+$
state_province_region
string

State associated with the contact. This is a reserved field.

minLength: 0
postal_code
integer

Zipcode associated with the address of the contact. This is a reserved field.

country
string

Country associated with the address of the contact. This is a reserved field.

minLength: 0
list_ids
array[string]

IDs of all lists the contact is part of

uniqueItems: True
custom_fields
object

The user may choose to create up to 120 custom fields or none at all. This is not a reserved field.

custom_field_name1
string
minLength: 0
custom_field_name2
string
minLength: 0
string
segment_ids
array[string]

IDs of all segments the contact is part of

uniqueItems: True
created_at
string

ISO8601 timestamp of when the object was created

required
updated_at
string

ISO8601 timestamp of when the object was last updated

required
sample_updated_at
string

ISO8601 timestamp of when the samples were last updated

required
next_sample_update
string

ISO8601 timestamp of when the samples will be next updated

required
parent_list_ids
array[string]

The array of list ids to filter contacts on when building this segment. It allows only one such list id for now. We will support more in future

uniqueItems: True
required
query_version
string

If not set, segment contains a Query for use with Segment v1 APIs. If set to '2', segment contains a SQL query for use in v2.

required
status
object

Segment status indicates whether the segment's contacts will be updated periodically

required
query_validation
string

Status of query validation. PENDING, VALID, or INVALID

required
error_message
string

Describes any errors that were encountered during query validation

object

If the request is incorrect, an array of errors will be returned.

errors
array[object]
required
field
string

the field in the request body that is incorrect

message
string

a description of what is specifically wrong with the field passed in the request

No response body.
No response body.
object

If the request is incorrect, an array of errors will be returned.

errors
array[object]
required
field
string

the field in the request body that is incorrect

message
string

a description of what is specifically wrong with the field passed in the request

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more