Menu

Contacts

Search Contacts

Search Contacts

POST /marketing/contacts/search

Use this endpoint to locate contacts.

The request body's query field accepts valid SGQL for searching for a contact.

Because contact emails are stored in lower case, using SGQL to search by email address requires the provided email address to be in lower case. The SGQL lower() function can be used for this.

Only the first 50 contacts that meet the search criteria will be returned.

If the query takes longer than 20 seconds, a 408 Request Timeout status will be returned.

Formatting the created_at and updated_at values as Unix timestamps is deprecated. Instead they are returned as ISO format as string.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Request Body

object
query
string

An SGQL search string or other pattern.

required
{
  "query": "email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs')"
}

Responses

object
result
array[object]
id
string
first_name
string
last_name
string
unique_name
string
email
string
alternate_emails
array[string]
address_line_1
string
address_line_2
string
city
string
state_province_region
string
country
string
postal_code
string
phone_number
string
whatsapp
string
line
string
facebook
string
list_ids
array[string]
segment_ids
array[string]
custom_fields
object
created_at
string
updated_at
string
_metadata
object
self
string

A link to this object.

_metadata
object
self
string

A link to this object.

contact_count
number

The total number of contacts matched.

required
object
errors
array[object]
field
string
message
string
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
No response body.
object
errors
array[object]
message
string
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