get_contacts
Section: Contacts
Version: 1.5.0
Get list of contacts from the account.
Conditions:
- campaigns / get_campaigns (optional) – Search only in given campaigns. Uses OR logic. If those params are not given, search is performed in all campaigns within the account. Check IDs in conditions for detailed explanation.
- name (optional) – Use text operators to narrow down search results to specific contact names.
- email (optional) – Use text operators to narrow down search results to specific contact emails.
- created_on (optional) – Use time operators to narrow down search results to specific contact creation date. Multiple operators are allowed and logic AND is used so date range can also be expressed.
- changed_on (optional) – Use time operators to narrow down search results to specific contact modification date. Multiple operators are allowed and logic AND is used so date range can also be expressed.
- origin (optional) – Narrow down search results by contacts’ origin (subscription method). Allowed values are import, email, www, panel, leads, sale, api, forward, survey, iphone, copy, landing_page.
- cycle_day (optional) – Use numeric operators to narrow down search results to specific days of the autoresponder cycles assigned to the contacts. To find contacts that are on day 2 you have to use { "EQUALS" : 2 }. To find inactive contacts pass { "EQUALS" : null } condition. Note that the fact that contact is on day 2 does not mean he received all autoresponder messages for day 2, there are factors such as excluded of days of week that may cause message to be delayed beyond its cycle_day.
- customs (optional) – Use text operators to narrow down search results to contacts having specific customs. Uses AND logic. Note that if you need OR logic you can use MATCHES operator and use alternative in regular expression. Contacts that don’t have a custom of given name are not returned in results. If custom is multi-value then “any” junction is used: condition is true if any custom value tests true according to the operator used.
- geo (optional) – Use operators to narrow down search results to specific contact geo location. Precisely text operators are allowed for country, country_code, city, numeric operators are allowed for latitude and longitude (values are decimal numbers, like -54.5). Uses AND logic. Contacts that don’t have a geo location data are not returned in results.
- clicks / get_clicks (optional) – Use to narrow down search results to the contacts that clicked specific links. Uses AND logic. Check IDs in conditions for detailed explanation.
- opens / get_opens (optional) – Use to narrow down search results to contacts that opened specific messages. Uses AND logic. Check IDs in conditions for detailed explanation.
- goals / get_goals (optional) – Use to narrow down search results to contacts that reached specific goals. Uses AND logic. Check IDs in conditions for detailed explanation.
- sends / get_sends (optional) – Use to narrow down search results to contacts that specific messages was send to. Uses AND logic. Check IDs in conditions for detailed explanation.
- segmentation (optional) – Allows to fetch big results in smaller packs. Split value defines the number of packs to which contacts will be split. Group defines which pack will be returned in results. Check result chunks to understand difference between segmentation and paging.
- pager (optional) – Allows to fetch big results in equal, semi-sorted chunks. Allowed values for order_by are "name", "email", "origin". Allowed values for direction are "ascending", "descending". Check result chunks to understand difference between segmentation and paging.
Warning: Email is unique within a campaign, but if search is performed on multiple campaigns, one email address may occur multiple times in results.
Hint: Value of cycle_day is approximate. To count contacts for specific time-based autoresponder message use get_autoresponder_contacts_amount.
Hint: Result Chunks:
If you want to synchronize data in multiple parallel threads/processes use segmentation. For example first process/thread calls get_contacts with split = 3 and pack = 1. Second process/thread calls get_contacts with split = 3 and pack = 2. And third process/thread calls get_contacts with split = 3 and pack = 3. Segmentation has following properties:
- Odd value MUST be used as split.
- Amount of contacts in each pack is almost equal.
- Packs don’t overlap. The sum of contacts in packs 1/3, 2/3 and 3/3 is the same as in method call without segmentation.
- Contacts stay in their packs forever. If specific contact is in pack 23/55 it will always be located in it no matter if the contacts list has changed.
- It is vulnerable to contacts list changes. For example get_contact with order_by = "email", direction = "ascending", limit = 2, offset = 0 returned "a@example.com" and "c@example.com" contacts. Then "b@example.com" subscribed. Now when you fetch next page with order_by = "email", direction = "ascending", limit = 2, offset = 2 you will get "c@example.com" email again because now it is third email on your list.
- Each chunk is returned as unordered hash so you should re-sort it using the same criteria as in order_by/direction. Use UTF-8 aware and case/accent insensitive algorithm.
Parameters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
string | API_KEY | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object |
|
Return Value | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
object | CONTACT_ID |
|
Example Request JSON
[
"API_KEY",
{
"campaigns": [
"CAMPAIGN_ID",
"CAMPAIGN_ID"
],
"get_campaigns": {
"name": {
"CONTAINS": "my_campaign_%"
}
},
"name": {
"OPERATOR": "value"
},
"email": {
"OPERATOR": "value"
},
"created_on": {
"OPERATOR": "value"
},
"changed_on": {
"OPERATOR": "value"
},
"origin": "value",
"cycle_day": {
"OPERATOR": "value"
},
"customs": [
{
"name": "name_1_value",
"content": {
"OPERATOR": "content_1_value"
}
},
{
"name": "name_2_value",
"content": {
"OPERATOR": "content_2_value"
}
}
],
"geoip": {
"latitude": {
"OPERATOR": "latitude_value"
},
"longitude": {
"OPERATOR": "longitude_value"
},
"country": {
"OPERATOR": "country_value"
},
"country_code": {
"OPERATOR": "country_code_value"
},
"city": {
"OPERATOR": "city_value"
}
},
"clicks": [
"LINK_ID",
"LINK_ID"
],
"get_clicks": {
"url": {
"CONTAINS": "my_link_%"
}
},
"opens": [
"MESSAGE_ID",
"MESSAGE_ID"
],
"get_opens": {
"name": {
"CONTAINS": "my_message_%"
}
},
"goals": [
"GOAL_ID",
"GOAL_ID"
],
"get_goals": {
"profile": {
"CONTAINS": "my_profile_%"
}
},
"sends": [
"MESSAGE_ID",
"MESSAGE_ID"
],
"get_sends": {
"name": {
"CONTAINS": "my_message_%"
}
},
"segmentation": {
"split": "split_value",
"pack": "pack_value"
}
}
]
Example Response JSON
{
"CONTACT_ID": {
"campaign": "CAMPAIGN_ID",
"name": "My Contact Name",
"email": "my_contact_2@emailaddress.com",
"origin": "api",
"ip": "1.1.1.1",
"cycle_day": null,
"changed_on": null,
"created_on": "2010-01-01 00:00:00"
}
}
API-wide Errors | |
---|---|
API key verification failed | API key verification failed |
API client IP not allowed | API client IP not allowed |
Invalid params | Attribute params must be reference to hash |