Menu

Get Segment by ID

Get Segment by ID

GET /segments/2.0/{segment_id}

The Segmentation V2 API is currently in private beta. If you'd like to be added to the beta, please fill out this form

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Path Parameters

segment_id
string
required

Query String

contacts_sample
boolean

Defaults to true. Set to false to exclude the contacts_sample in the response.

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

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

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.