The Find in List command allows you to search and return data for one or more contacts in a specific List.
Arguments
The Find in List command requires the following arguments: Command, Realm, Password, List ID, and Email or Identity.
api_web?r=myrealm&p=mypass&c=findinlist&email=jane@domain.com&list_id=5
The command is ‘findinlist', the realm is ‘myrealm’ and the password is ‘mypass’. The Contact to find is in List with ID '5' with email 'jane@domain.com' .
api_web?r=myrealm&p=mypass&c=findinlist&identity_field=custom_id&identity_value=112&list_id=5
The command is ‘findinlist', the realm is ‘myrealm’ and the password is ‘mypass’. The Contact to find is in List with ID '5' and has a value of '112' in the custom field 'id'.
The command will attempt to find any contact record in the realm with the specified email address with a subscription in the specific list and return the results. A successful search will return the contact ID and email address for each matching Contact.
You can also output the first name, last name and List IDs of the subscribed lists by using the output_format argument. For more data information about a Contact, use the Contact Details command.
Though you may generally be searching for a specific contact, you may also need to find a group of close matches using a combination of the email address, first name, and/or last name
To do this, use part of an email address, or search a combination of email, first and/or last name. Be sure to set the Exact flag to 0 to return all matching results. The maximum number of results returned is 250 contacts. If more than 250 matching contacts exist in a realm, you can refine your search criteria.
The Find in List command supports the following arguments:
|
Name |
Req? |
Description |
Argument |
|
Command |
Yes |
Defines the command to use. |
cmd=findinlist c=findinlist |
|
Realm |
Yes |
Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match. |
realm=[realm_name] r=[realm_name] |
|
Password |
Yes |
Authentication code for API access. This is required, and the command will fail if the realm and password do not match. |
pwd=[password] p=[password] |
| List ID | Yes |
Identifier of the List to search. |
list_id=[list_id] |
|
|
* |
Identifier of the Subscribrer to find. Full or partial email address is allowed. Email is required unless Identity is used. Not supported in Customer Key realm. |
email=[email] |
|
First Name |
Full or partial first name to search in conjunction with the Email and/or Last Name. Not supported in Customer Key realm. |
first=[first_name] |
|
|
Last Name |
Full or partial last name to search in conjunction with the Email and/or First Name. Not supported in Customer Key realm. |
last=[last_name] |
|
|
Identity Field |
* |
Specifies which field to use to lookup the contact to be updated. The Identity field must contain unique data for each contact. Required if Email is not used. Not supported in Customer Key realm. |
identity_field=[custom_field_name]
|
|
Identity Value |
*
|
The value to match for the specified Identity field. | identity_value=[value] |
|
Customer Key |
*
|
Identifier of the contact to find in lieu of Email or Identity Field. Does not work with any combination of Email, First, Last, Identity. Only available if enabled for realm. |
customer_key=[customer_key] |
|
Limit Results |
Limits the number of records returned from 1 to 250. |
limit=[1 to 250] DEFAULT==250 |
|
|
Exact Match |
To limit your results to the exact specified values, set exact to 1. If set to 0, all contacts that have a combination of the values will be returned. |
exact=[0,1] DEFAULT==1 |
|
|
Output Format |
To specify the format of the list output, use one of two arguments. If no argument is included, the default output is space-delimited plain text string, which may not include all data columns. |
csv=1 or output_format=[csv,csv_tab, csv_pipe,xml] |
|
|
Header |
To define the data with a label, use the Header argument. This can only be used in conjunction with the output format, and does not affect XML. |
headers=[0,1]
DEFAULT==0 |
Example
Using all commands and arguments (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=findinlist&list_id=5&exact=0&limit=5&email= @domain.com&first=j&output_format=csv&headers=1
The command will find the first five contacts that have an email address like '@domain.com' and first name like 'j' and are subscribed to the list '5'.
Successful results return:
"subscriber_id","email","first","last","lists" "5","jane@domain.com","Jane","Doe","5" "6","jane@domain.com","Jayne","Doe","5" "8","john.smith@domain.com","John","Doe","5"
Customer Key Example
Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, you may use the customer_key to find a contact instead of email or identity_field:
api_web?r=myrealm&p=mypass&&c=findinlist&list_id=5&exact=1&customer_key=11293&output_format=csv&headers=1
Successful results return:
"subscriber_id","customer_key","email","first","last","lists" "5","11293","jane@domain.com","Jane","Doe","5"
Results
The Find in List command outputs either a SUCCESS or FAILURE message.
SUCCESS
The Find in List command does not explicitly return a Success code. Instead, it outputs the contact details in plain text format. Use the output_format argument to return the results in an alternate format.
FAILURE
A Find in List command will fail for several reasons. The result format is:
FAILURE: [Reason]