« Back to Documentation Overview

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.
If you want to display paged output use pager. It has the same effect as ORDER BY ... ASC|DESC LIMIT ... OFFSET syntax in SQL. Paging has following properties:
  • 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.
Use the right tool for your job - segmentation is not suitable for creating pagers (contacts are unordered and each chunk may have slightly different amount of elements) and pager is not suitable for parallel synchronization (chunks are not guaranteed to be mutually exclusive).


Parameters
stringAPI_KEY
object
arraycampaigns
stringCAMPAIGN_ID
stringCAMPAIGN_ID
objectget_campaigns
objectname
stringCONTAINSmy_campaign_%
objectname
stringOPERATORvalue
objectemail
stringOPERATORvalue
objectcreated_on
stringOPERATORvalue
objectchanged_on
stringOPERATORvalue
stringoriginvalue
objectcycle_day
stringOPERATORvalue
arraycustoms
object
stringnamename_1_value
objectcontent
stringOPERATORcontent_1_value
object
stringnamename_2_value
objectcontent
stringOPERATORcontent_2_value
objectgeoip
objectlatitude
stringOPERATORlatitude_value
objectlongitude
stringOPERATORlongitude_value
objectcountry
stringOPERATORcountry_value
objectcountry_code
stringOPERATORcountry_code_value
objectcity
stringOPERATORcity_value
arrayclicks
stringLINK_ID
stringLINK_ID
objectget_clicks
objecturl
stringCONTAINSmy_link_%
arrayopens
stringMESSAGE_ID
stringMESSAGE_ID
objectget_opens
objectname
stringCONTAINSmy_message_%
arraygoals
stringGOAL_ID
stringGOAL_ID
objectget_goals
objectprofile
stringCONTAINSmy_profile_%
arraysends
stringMESSAGE_ID
stringMESSAGE_ID
objectget_sends
objectname
stringCONTAINSmy_message_%
objectsegmentation
stringsplitsplit_value
stringpackpack_value
Return Value
objectCONTACT_ID
stringcampaignCAMPAIGN_ID
stringnameMy Contact Name
stringemailmy_contact_2@emailaddress.com
stringoriginapi
stringip1.1.1.1
stringcycle_dayget_contacts_cycle_day__string
stringchanged_onget_contacts_changed_on__string
stringcreated_on2010-01-01 00:00:00

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