API resources: Profile search – MC Professional

The Profile Search resource lets a third-party client create and run profile searches through the MC Professional API.

On this page

Overview
Create a profile search
Get a profile search by search ID

Overview

The MC Professional API Profile Search resource allows a 3rd party client to create a profile search and retrieve an existing profile search.

To search for a list of profiles that match a set of search criteria, a profile search must first be created with the search criteria. The profile search creation process will generate a search ID which can then be used with the MC Professional API Profile resource to return the profiles that match the search criteria. The Get a List of Profiles by Search ID section details how to use the search ID to get the profile search results.

Create a profile search

This resource creates a profile search by accepting search criteria and returns a search ID. The search ID can then be used to retrieve a list of profiles matching the search criteria. The Get a List of Profiles by Search ID section details how to use the search ID.

Scope

To access this resource, the access token must have the read scope.

Permissions

This resource is available to users.

Request

The request to create a profile search is an HTTP POST to the /api/v1/profile/search endpoint. The following is the format of the request:

orgId: the MemberClicks organization ID
accessToken: the access token issued by the authorization server
attributeName: the built-in, system or custom attribute name
attributeValue: the value or values to search for. The format of the attributeValue depends on the type of attribute. Any text values entered for attributeValue are case insensitive.

Example

In this example, we will create a profile search where the last name contains "Burton", the primary email contains "memberclicks.com", the Birthday custom attribute is between "01/01/1980" and "12/31/1985" inclusive, the School custom attribute contains "University", the Sports custom attribute has "Softball" or "Tennis" selected, the member status is "Active" and the member type is "Member".

Using the example values below, the following is the resulting request:

orgId: apiexample
accessToken: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njg0MjMzNTUsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfRklOQU5DSUFMX0FETUlOIiwiUk9MRV9VU0VSIiwiUk9MRV9DTVNfQURNSU4iLCJST0xFX1BST0ZJTEVfSU1QT1JUX0FETUlOIiwiUk9MRV9QUk9GSUxFX0FETUlOIiwiUk9MRV9DT01NVU5JVFlfQURNSU4iLCJST0xFX01FTUJFUlNISVBfQURNSU4iLCJST0xFX0ZPUk1TX0FETUlOIiwiUk9MRV9SRVBPUlRJTkdfQURNSU4iXSwidXNlcklkIjoxMDAxMzQ1NjMwLCJqdGkiOiJhOWRiYTVkZC1kMDk4LTQxMTUtODFjMS1lOTZhMGI1OTNjZGIiLCJjbGllbnRfaWQiOiI4WmdaeFY5QjhyZHdWWEo4bHp1aCJ9.JHZWALRZVH-EhuP62QdlL-v6iT7VFaFYRjThhr0Rerg

Response

A successful request will return an HTTP status 201 Created with the response in the following format:

timestamp: the timestamp when the profile search was created (milliseconds since Unix epoch)
id: the search ID
url: the URL for this profile search. The Get a Profile Search by Search ID section details how to use this URL.
expireDate: the date and time that the search expires. The profile search expires in one hour and is reset every time the search ID is used.
attributeName: the built-in, system or custom attribute name
attributeValue: the value or values to search for
profilesUrl: the URL for the list of profiles that match the search criteria. The Get a List of Profiles by Search ID section details how to use this URL.

Example

The following is the response for the example request above:

More examples

This section contains more example requests for creating a profile search for every type of built-in, system and custom attribute. The following values will be used in the requests:

orgId: apiexample
accessToken: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njg0MjkwODUsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfRklOQU5DSUFMX0FETUlOIiwiUk9MRV9VU0VSIiwiUk9MRV9DTVNfQURNSU4iLCJST0xFX1BST0ZJTEVfSU1QT1JUX0FETUlOIiwiUk9MRV9QUk9GSUxFX0FETUlOIiwiUk9MRV9DT01NVU5JVFlfQURNSU4iLCJST0xFX01FTUJFUlNISVBfQURNSU4iLCJST0xFX0ZPUk1TX0FETUlOIiwiUk9MRV9SRVBPUlRJTkdfQURNSU4iXSwidXNlcklkIjoxMDAxMzQ1NjMwLCJqdGkiOiI0YjQzM2Y3Ni02MjdiLTRhZDAtYWY5OS0xYmIzMDVjNTg2ZDUiLCJjbGllbnRfaWQiOiI4WmdaeFY5QjhyZHdWWEo4bHp1aCJ9.pweM-vqkOlb1EUItSfbFrrbVrC-OKGMhIDiAFPt4m8I

Search by name prefix example

Create a profile search where the name prefix is "Mr."

Search by first name example

Create a profile search where the first name contains "Jeff".

Search by middle name example

Create a profile search where the middle name contains "Matt"

Search by last name example

Create a profile search where the last name contains "Williams"

Search by name suffix example

Create a profile search where the name suffix is "II"

Search by contact name example

Create a profile search where the contact name contains "ed"

Search by email example

Create a profile search where any email address contains "memberclicks.com". This searches the primary email, organization email and all emails with custom labels.

Create a profile search where the primary email address contains "memberclicks.com".

Create a profile search where the "Work" email address contains "memberclicks.com".

Search by address line 1 example

Create a profile search where the any address line 1 contains "street". This searches the primary address, organization address and all addresses with custom labels.

Create a profile search where the primary address line 1 contains "street".

Create a profile search where the "Business" address line 1 contains "street".

Search by address line 2 example

Create a profile search where the any address line 2 contains "box". This searches the primary address, organization address and all addresses with custom labels.

Create a profile search where the primary address line 2 contains "box".

Create a profile search where the "Business" address line 2 contains "box".

Search by address city example

Create a profile search where any address city contains "Atlanta". This searches the primary address, organization address and all addresses with custom labels.

Create a profile search where the primary address city contains "Atlanta".

Create a profile search where the "Business" address city contains "Atlanta".

Search by address state/Province example

When searching by a state/province, you can enter the full state/province name or abbreviation. For example, you can enter "Georgia" or "GA" for the attributeValue.

Create a profile search where any address state is "Georgia". This searches the primary address, organization address and all addresses with custom labels.

Create a profile search where the primary address state is "GA".

Create a profile search where the "Business" address state is "Georgia".

Search by address zip code example

Create a profile search where any address zip code contains "33805". This searches the primary address, organization address and all addresses with custom labels.

Create a profile search where the primary address zip code contains "33805".

Create a profile search where the "Business" address zip code contains "33805".

Search by address country example

Create a profile search where any address country is "United States". This searches the primary address, organization address and all addresses with custom labels.

Create a profile search where the primary address country is "United States".

Create a profile search where the "Business" address country is "United States".

Search by phone example

Create a profile search where any phone number contains "404". This searches the primary phone number, organization phone number and all phone numbers with custom labels.

Create a profile search where the primary phone number contains "404".

Create a profile search where the "Mobile" phone number contains "404".

Search by organization example

Create a profile search where the organization contains "photo".

Search by organization email example

Create a profile search where the organization name contains "memberclicks.com".

Search by organization address line 1 example

Create a profile search where the organization address line 1 contains "road".

Search by organization address line 2 example

Create a profile search where the organization address line 2 contains "suite".

Search by organization address city example

Create a profile search where the organization address city contains "new york".

Search by organization address state example

When searching by a state/province, you can enter the full state/province name or abbreviation. For example, you can enter "California" or "CA" for the attributeValue.

Create a profile search where the organization address state is "California".

Search by organization address zip example

Create a profile search where the organization address zip code contains "32209".

Search by organization address country example

Create a profile search where the organization address country is "United Kingdom".

Search by organization phone example

Create a profile search where the organization phone contains "770".

Search by created date example

When searching by created date, you can enter a single date, a date range using start date and end date, start date only, end date only, or a predefined set of date ranges. The recommended date format is "MM/DD/YYYY" but "M/D/YYYY" is also accepted. The following are the valid predefined set of date ranges:

Last 90 Days
Last 30 Days
Last 7 Days
Last 3 Months
Last Month
This Month
Last Year
This Year

Create a profile search where the created date is "06/15/2015".

Create a profile search where the created date is between "01/01/2015" and "12/31/2015" inclusive.

Create a profile search where the created date is "02/01/2010" or after.

Create a profile search where the created date is "11/30/2015" or before.

Create a profile search where the created date is within the last 30 days.

Search by expiration date example

When searching by expiration date, you can enter a single date, a date range using start date and end date, start date only, end date only, or a predefined set of date ranges. The recommended date format is "MM/DD/YYYY" but "M/D/YYYY" is also accepted. The following are the valid predefined set of date ranges:

Last 90 Days
Last 30 Days
Last 7 Days
Next 7 Days
Next 30 Days
Next 90 Days
Last 3 Months
Last Month
This Month
Next Month
Next 3 Months
Last Year
This Year
Next Year

Create a profile search where the expiration date is "12/31/2015".

Create a profile search where the expiration date is between "03/01/2017" and "03/31/2017" inclusive.

Create a profile search where the expiration date is "01/01/2017" or after.

Create a profile search where the expiration date is "12/31/2017" or before.

Create a profile search where the expiration date is within the next year.

Search by group example

When searching by group, you can enter a single group name or a list of group names.

Create a profile search where the group is "Member".

Create a profile search where the group is "Associate", "Member" or "Student".

Search by join date example

When searching by join date, you can enter a single date, a date range using start date and end date, start date only, end date only, or a predefined set of date ranges. The recommended date format is "MM/DD/YYYY" but "M/D/YYYY" is also accepted. The following are the valid predefined set of date ranges:

Last 90 Days
Last 30 Days
Last 7 Days
Last 3 Months
Last Month
This Month
Last Year
This Year

Create a profile search where the join date is "06/15/2015".

Create a profile search where the join date is between "01/01/2015" and "12/31/2015" inclusive.

Create a profile search where the join date is "02/01/2010" or after.

Create a profile search where the join date is "11/30/2015" or before.

Create a profile search where the join date is within the last 3 months.

Search by last renewal date example

When searching by last renewal date, you can enter a single date, a date range using start date and end date, start date only, end date only, or a predefined set of date ranges. The recommended date format is "MM/DD/YYYY" but "M/D/YYYY" is also accepted. The following are the valid predefined set of date ranges:

Last 90 Days
Last 30 Days
Last 7 Days
Last 3 Months
Last Month
This Month
Last Year
This Year

Create a profile search where the last renewal date is "06/15/2015".

Create a profile search where the last renewal date is between "01/01/2015" and "12/31/2015" inclusive.

Create a profile search where the last renewal date is "02/01/2010" or after.

Create a profile search where the last renewal date is "11/30/2015" or before.

Create a profile search where the last renewal date is within this year.

Search by last modified date example

When searching by last modified date, you can enter a single date, a date range using start date and end date, start date only, end date only, or a predefined set of date ranges. The recommended date format is "MM/DD/YYYY" but "M/D/YYYY" is also accepted. The following are the valid predefined set of date ranges:

Last 90 Days
Last 30 Days
Last 7 Days
Last 3 Months
Last Month
This Month
Last Year
This Year

Create a profile search where the last modified date is "06/15/2015".

Create a profile search where the last modified date is between "01/01/2015" and "12/31/2015" inclusive.

Create a profile search where the last modified date is "02/01/2010" or after.

Create a profile search where the last modified date is "11/30/2015" or before.

Create a profile search where the last modified date is within the last 7 days.

Search by member number example

When searching by member number, you can enter a single member number or a list of member numbers.

Create a profile search where the member number is 10.

Create a profile search where the member number is 10, 100, 123 or 201.

Search by member status example

When searching by member status, you can enter a single status or a list of statuses. The following are the valid statuses:

Pending
Active
Graced
Lapsed
Deceased

Create a profile search where the member status is "Active".

Create a profile search where the member status is "Pending", "Active", "Graced" or .

Search by member type example

When searching by member type, you can enter a single member type name or a list of member type names.

Create a profile search where the member type is "Member".

Create a profile search where the member type is "Admin", "Associate" or "Student".

Search by username example

Create a profile search where the username contains "smith".

Search by deleted example

When searching by deleted, the valid values are true and false. If the deleted criteria is not included when creating the profile search, the results will only include profiles that are not deleted.

Create a profile search where the profile is deleted.

Create a profile search regardless of whether a profile is deleted or not.

Search by text custom attribute example

Create a profile search where the School custom attribute contains "college".

Search by number custom attribute example

Create a profile search where the Number of Employees custom attribute is exactly "10".

Search by date/Time custom attribute example

When searching by a date/time custom attribute, you can enter a single date, a date range using start date and end date, start date only, end date only, or a predefined set of date ranges. The recommended date format is "MM/DD/YYYY" but "M/D/YYYY" is also accepted. The following are the valid predefined set of date ranges:

Last 90 Days
Last 30 Days
Last 7 Days
Next 7 Days
Next 30 Days
Next 90 Days
Last 3 Months
Last Month
This Month
Next Month
Next 3 Months
Last Year
This Year
Next Year

Create a profile search where the Birthday custom attribute is "01/28/1981".

Create a profile search where the Birthday custom attribute is between "01/01/1990" and "12/31/1999" inclusive.

Create a profile search where the Birthday custom attribute is "01/01/2000" or after.

Create a profile search where the Birthday custom attribute is "12/31/1979" or before.

Create a profile search where the Birthday custom attribute is within the last year.

Search by selection set custom attribute example

When searching by a selection set custom attribute, you can enter a single selection set option or a list of selection set options.

Create a profile search where the Sports custom attribute has "Football" selected.

Create a profile search where the Sports custom attribute has "Baseball", Basketball" or "Football" selected.

Create a profile search where the Sports custom attribute has no options selected

Search by state custom attribute example

When searching by a state custom attribute, you can enter a single state or a list of states. You can also enter the full state/province name or abbreviation. For example, you can enter "Florida" or "FL" for the attributeValue.

Create a profile search where the State custom attribute is "Florida".

Create a profile search where the State custom attribute has "Florida", "GA" or "South Carolina" selected.

Create a profile search where the State custom attribute that has no states selected.

Search by country custom attribute example

When searching by a country custom attribute, you can enter a single country or a list of countries.

Create a profile search where the Country custom attribute is "United States".

Create a profile search where the Country custom attribute has "France", "Germany" or "Spain" selected.

Create a profile search where the Country custom attribute has no countries selected.

Search by event registrant status example

When searching by event registrant status, you can enter a single event with a single event registrant status, a single event with multiple event registrant statuses which will be combined with a logical "or", or multiple events with a single event registrant status each that will be combined with a logical "and".

The API Resources: Events page details how to retrieve a list of events. The event is identified with the name and date fields (though you may use name alone if it is unique).

The event registrant statuses are identified with the status field. The following are the valid predefined set of event registrant statuses:

Registered
Cancelled
Attended
No Show
Not Registered

Create a profile search for profiles that registered for the 'Summer Conference' event.

Create a profile search for profiles that registered for or attended the 2017 'Winter Conference' event.

Create a profile search for profiles that attended the 2017 'Winter Conference' event and are registered for the 2018 'Winter Conference' event.

Search by multiple attributes example

Profile searches support searching by multiple attributes. Multiple attributes are combined with a logical "and" operation so that profiles that appear in the search results match every attribute criteria.

Create a profile search where the the last name contains "Burton", the primary email contains "memberclicks.com", the Birthday custom attribute is between "01/01/1980" and "12/31/1985" inclusive, the School custom attribute contains "University", the Sports custom attribute has "Softball" or "Tennis" selected, the member status is "Active" and the member type is "Member".

Get a profile search by search ID

This resource returns an existing profile search by search ID.

Scope

To access this resource, the access token must have the read scope.

Permissions

This resource is available to users.

Request

The request to get a profile search is an HTTP GET to the /api/v1/profile/search/<searchId> endpoint. The following is the format of the request:

searchId: the search ID
orgId: the MemberClicks organization ID
accessToken: the access token issued by the authorization server

Example

Using the example values below, the following is the resulting request:

searchId: 1a11b80c-5a4a-4759-a701-a4016798b96c
orgId: apiexample
accessToken: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0Njg0MTYzODgsInVzZXJfbmFtZSI6IjEwMDEzNDU2MzAiLCJzY29wZSI6WyJyZWFkIl0sInNlcnZpY2VJZCI6NzM0MCwiYXV0aG9yaXRpZXMiOlsiUk9MRV9BRE1JTiIsIlJPTEVfRklOQU5DSUFMX0FETUlOIiwiUk9MRV9VU0VSIiwiUk9MRV9DTVNfQURNSU4iLCJST0xFX1BST0ZJTEVfSU1QT1JUX0FETUlOIiwiUk9MRV9QUk9GSUxFX0FETUlOIiwiUk9MRV9DT01NVU5JVFlfQURNSU4iLCJST0xFX01FTUJFUlNISVBfQURNSU4iLCJST0xFX0ZPUk1TX0FETUlOIiwiUk9MRV9SRVBPUlRJTkdfQURNSU4iXSwidXNlcklkIjoxMDAxMzQ1NjMwLCJqdGkiOiIyMWY2NjIxMC1hODU5LTQwODgtYWU1NS1iMGViODUxNjNjZDUiLCJjbGllbnRfaWQiOiI4WmdaeFY5QjhyZHdWWEo4bHp1aCJ9.JUEzsdf7EozLwFZcNMdXVoPR-RPUvHDX1Jgxu6vokRA

Response

A successful request will return an HTTP status 200 OK with the response in the following format:

id: the search ID
expireDate: the date and time that the search expires. The profile search expires in one hour and is reset every time the search ID is used.
attributeName: the built-in, system or custom attribute name
attributeValue: the value or values to search for

Example

The following is the response for the example request above:

Articles in this section

Overview

Create a profile search

Scope

Permissions

Request

Example

Response

Example

More examples

Search by name prefix example

Search by first name example

Search by middle name example

Search by last name example

Search by name suffix example

Search by contact name example

Search by email example

Search by address line 1 example

Search by address line 2 example

Search by address city example

Search by address state/Province example

Search by address zip code example

Search by address country example

Search by phone example

Search by organization example

Search by organization email example

Search by organization address line 1 example

Search by organization address line 2 example

Search by organization address city example

Search by organization address state example

Search by organization address zip example

Search by organization address country example

Search by organization phone example

Search by created date example

Search by expiration date example

Search by group example

Search by join date example

Search by last renewal date example

Search by last modified date example

Search by member number example

Search by member status example

Search by member type example

Search by username example

Search by deleted example

Search by text custom attribute example

Search by number custom attribute example

Search by date/Time custom attribute example

Search by selection set custom attribute example

Search by state custom attribute example

Search by country custom attribute example

Search by event registrant status example

Search by multiple attributes example

Get a profile search by search ID

Scope

Permissions

Request

Example

Response

Example

Related articles