Follow

Find Subscriber in List

The Find in List command allows you to search and return data for one or more subscribers 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 Subscriber 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 Subscriber 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 subscriber 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 subscriber ID and email address for each matching Subscriber. 

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 Subscriber, use the Subscriber Details command.

Though you may generally be searching for a specific subscriber, 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 subscribers.  If more than 250 matching subscribers 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]

Email

*

Identifier of the Subscribrer to find.  Full or partial email address is allowed.  Email is required unless Identity is used.

email=[email]

First Name

 

Full or partial first name to search in conjunction with the Email and/or Last Name.

first=[first_name]

Last Name

 

Full or partial last name to search in conjunction with the Email and/or First Name.

last=[last_name]

Identity Field

*

Specifies which field to use to lookup the subscriber to be updated.  The Identity field must contain unique data for each subscriber.  Required if Email is not used.

identity_field=[custom_field_name]

 

Identity Value

*

 

The value to match for the specified Identity field. identity_value=[value]

Customer Key

*

 

Identifier of the subscriber to find in lieu of Email or Identity Field. Only available on some systems.

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 subscribers that have a combination of the values will be returned.

exact=[0,1]

DEFAULT==0

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 subscribers 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 subscriber.  If your realm has Customer Key enabled, you may use the customer_key to find a subscriber 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 subscriber 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]  

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

Comments

Powered by Zendesk