Follow

Get Contact by Filter

The Get Contact by Filter command allows you to get the Contact Data for one or more Contacts in a List based on a compound filter, or query string.

GET /subscribers?querystring

https://[siteurl]/rest/subscribers?querystring

The following queries are supported and can be combined in any order.  Customer Key is only supported in Realms in which the field is enabled:

firstName=[subscriber.firstname]
lastName=[subscriber.lastname]
email=[subscriber.emal]
customerKey=[subscriber.customerkey]

Request Body Parameters

The Get Contact by Filter command requires the URI call with the contacts parameter. Optional Filters include Email, First Name, Last Name, and Customer Key parameters. No additional fields are required in the JSON.    

The query strings 'firstName', 'lastName', and 'customerKey' are case sensitive and must be defined as in the example above.  If the query string is incorrect, it is ignored and the command returns all Contacts in the Realm, like the Get All Contacts command.

If any of the query strings contain spaces, URL encode the space with '%20', for instance:

  • My First Name

    becomes

  • My%20First%20Name

Request Body Example

Using Get Contact by Filter:

curl --request GET \ 
--url 'https://mail.mydomain.com/rest/subscribers?lastName=Doe&firstName=Jon' \
--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \
--header 'accept: application/vnd.whatcounts-v1+json' \
--header 'content-type: application/json' \
--include

Response Body

The response returns all API available Contact data in JSON format for each Contact in the Realm that matches any of the query fields.  If more than 500 results are found, the first 500 are displayed, and you must use the "skip" value to view the next 500.  

For example, to find the three groups of 500 Contacts in a List with 1455 matching Contacts, the URIs would be formatted as:

  1. https://[siteurl]/rest/subscribers?lastName=Doe&skip=0
  2. https://[siteurl]/rest/subscribers?lastName=Doe&skip=500
  3. https://[siteurl]/rest/subscribers?lastName=Doe&skip=1000

For more information about "skip", see Pagination.

Based on the example above, and three matching Contacts in the List, the response returns:

HTTP/1.1 200 OK
Server: serverName
Content-Type: application/json
Link: <https://mail.mydomain.com/rest/subscribers?lastName=Doe&firstName=Jon>;
Date: Fri, 17 Jun 2016 12:54:44 GMT
{
"subscriberId": 7160984
"realmId": 1561
"email": "j.doe@mydomain.com"
"firstName": "Jon"
"lastName": "Doe"
"company": "My Company"
"address1": "123 Some Street North"
"address2": "Suite 500"
"city": "My City"
"state": "WA"
"zip": "98000"
"country": "United States"
"phone": "(206) 555 1212"
"fax": ""
"createdDate": "May 21, 2012 9:14:16 AM"
"updatedDate": "Nov 2, 2015 10:31:27 AM"
"ipAddress": ""
"md5Encryption": "C8ADED17D5F088E8262BF31ED933B7D5"
"sha1Encryption": "356B1860247728C81486A35062688F302D96C3D0"
"skip": 3
"max": 0
}

{
"subscriberId": 7160985
"realmId": 1561
"email": "jon.doe@mydomain.com"
"firstName": "Jon"
"lastName": "Doe"
"company": ""
"address1": "321 Home Street South"
"address2": "Apt A"
"city": "My City"
"state": "WA"
"zip": "98000"
"country": "United States"
"phone": "(206) 555 2112"
"fax": ""
"createdDate": "May 21, 2012 9:14:16 AM"
"updatedDate": "Nov 2, 2015 10:31:27 AM"
"ipAddress": ""
"md5Encryption": "C8ADED17D5F088E8262BF31ED933B7D4"
"sha1Encryption": "356B1860247728C81486A35062688F302D96C2D1"
"customData": {
  "text": "text"
  "unicode": "unicode text"
  "large": "big"
  "number": 12
  "float": 12.12
  "date": "2016-07-04"
}
"skip": 2 
"max": 0 
} 
{ 
"subscriberId": 25158866 
"realmId": 1561 
"email": "jonD@mydomain.com" 
"firstName": "Jon" 
"lastName": "Doe" 
"company": "" 
"address1": "" 
"address2": "" 
"city": "" 
"state": "" 
"zip": "" 
"country": "" 
"phone": "" "
fax": "" 
"createdDate": "May 4, 2015 9:48:33 AM" 
"updatedDate": "Jun 13, 2016 1:06:46 PM" 
"md5Encryption": "5EBD1AAAEA76811129331B0FA649F48C" 
"sha1Encryption": "811B2A6ADC716AFFF1127A7B27D2F7B81167AB2E" 
"skip": 1 
"max": 0 
} 

Error Response

Error Response Codes include both Client Errors (4xx) and Server Errors (5xx).  Descriptions of each can be found in Response Codes

For example, if the Authorization is incorrect, the error would appear as:

{
"error": "Unauthorized"
"status": "Unauthorized"
"statusCode": 401
}

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk