Home

Download this help site
(PDF 80MB)

Download

Contacts API V1 call

Icon

Wild Apricot does not provide technical support for its API. If you encounter difficulties using it, add a post describing the issue to our Designers and Developers forum. Wild Apricot staff or other users may be able to suggest a solution.

You can use the Contacts API call to retrieve a detailed list of contacts, or details about a particular contact.

Responses to the Contacts API call can be filtered so that only those records that match the filter criteria will be returned. Filtering your search results can significantly reduce server response time. For more information, see Filtering API responses (below).

You can also control which fields are included in the results. For more information, see Selecting API response fields (below).

Retrieving information for a specific contact

The syntax for retrieving information about a specific contact is show below:

Example:

Retrieving information for all contacts

Retrieving information for all contacts is a two-stage process. First, you submit the search request as a Contacts API call and receive a result ID, as shown in the sample JSON code below.

Then, you pass the result ID as a parameter in a second Contacts API call. In response to the second API call, the server will return the search results.

Icon

Retrieving a complete list of your contacts can be an intensive process, so only one Contacts API call can be processed at a time. If multiple requests are received from the same account, they will be processed in the order in which they were received.

Search request syntax

Example:

Results request syntax

Example:

Parameters

The following parameters are used within the Contacts API call:

Variable

Description

{version}

The version number of the API. To retrieve a list of API versions, use the base API call.

{accountID}

The account identifier that appears on the Account and billing screen and is returned by the Accounts API call.

{contactID}

The ID of a contact. The contact ID is displayed in Wild Apricot on the contact record. You can retrieve a list of contact IDs by calling the Contacts API without specify a {contactID}.

{APIkey}

String of characters used to authenticate your account and prevent others from accessing your data. You can get your API key by clicking the API key link from the Settings screen. The API key can be passed as a URL parameter or as a HTTP header field.

{resultID}

The result identifier returned by the first Contacts API call. The identifier is passed as a parameter – with or without dashes – during the second Contacts API call.


The following parameters are optional:

Variable

Description

For more information, see...

$filter

Filters the results of the Contacts API call so that only those records that match the filter criteria are included.

Filtering API results

$select

Controls which fields are returned in the Contacts API call.

Selecting API response fields

Response fields

Search request

In the first and second stages of the contact search, the Contacts API returns the following information regarding the search request.

Field

Description

ResultId

The search request identifier. The identifier is passed as a parameter during the second Contacts API call.

ResultUrl

The address of the API call for the second Contacts API call – the results request.

Requested

The date and time the search request was submitted.

Processed

The date and time the search request was processed.

State

The state of the search request. Possible values are:

  • Waiting – the first stage in the process is complete, and the second stage has not yet been initiated.
  • Processing – the results request (from the second Contacts API call) has been submitted but the results have not yet been returned.
  • Complete – the search results have been successfully retrieved.
  • Failed – the search request has failed.

InitialQuery

The details of any $filter or $select parameters passed as part of the search request. The $filter parameter is used to filter the search results so that only those records that match the filter criteria will be returned. The $select parameter is used to control which fields are included in the results.

Search results

In the second stage of the contact search, the Contacts API returns the following information for each contact.

Field

Description

Id

The ID of the contact as displayed on their contact record.

Url

The address of the API call for this contact.

FirstName

The contact's first name.

LastName

The contact's last name.

EMail

The contact's email address.

ProfileLastUpdated

The date and time that common fields, membership fields, or member group participation were last updated for the contact.

MembershipLevel

The name and URL of the membership level assigned to the contact. If the contact is not a member, then the MembershipLevel field is not included in the results.

Status

The status of the contact's membership. Possible values are Active, Lapsed, PendingNew, PendingRenewal, and PendingUpgrade. The status is only included in the results if the contact is a member.

FieldValues

For each custom field you have added to your Wild Apricot database, the name of the field and its value for this contact are returned. As well, a number of system fields are returned. If a custom field is restricted to certain access levels, then CustomAccessLevel indicates the level to which the field is restricted. Possible values are AdminOnly, Member, and Public.

Sample JSON response

Sample XML response

Filtering API results

You can filter the results of the Contacts API call so that only those records that match the filter criteria will be included. You could, for example, you might want to retrieve only those contact records that have been added or updated after a certain date.

Icon

Filtering your search results can significantly reduce server response time.

You can filter using any field returned by the ContactFields API call. Within your filter criteria, you can use relational operators to include ranges of contacts, and use logical operators to combine multiple critieria.

$filter syntax

where {filterCriteria} is the criteria to be used to filter the search results.

Example:

In this example, only contacts whose balance is greater than 100 will be included in the search results.

Relational operators

You can use the following relational operators within your search criteria.

Operator

Description

Field types

Example

eq

Equal to

All

$filter='State/Prov' eq 'California'

ne

Not equal to

All

$filter=Organization ne 'Microsoft'

gt

Greater than

Number, DateTime

$filter=Balance gt 100

ge

Great than or equal to

Number, DateTime

$filter='Member since' ge 2010-01-01

lt

Less than

Number, DateTime

$filter='Total donated' lt 100

le

Less than or equal to

Number, DateTime

$filter='Renewal due' le 2013-08-25

substringof

Field includes specified value using the following format:
substringof('value', 'field')

String

$filter=substringof('Designer', 'Job title') eq true

Field names that include spaces or special characters (such as ? < & ) must be enclosed within single quotation marks.

Using the NULL constant, you can include or exclude contacts based on whether a particular field does or does not have a value. For example, if you wanted to include only contacts with a specified job title, the filter criteria might look something like this:

When specifying a value for date fields, you must use the yyyy-mm-dd date format, as shown in the following example:

Logical operators

You can use logical operators – AND and OR – to group multiple search criteria, and control whether either or both criteria must satisfied.

In the following example...

...contacts must reside in California and work for Google to be included in the search results.

In this example...

...contacts will included in the search results if they have donated more than $500 or if they have been members since January 1, 2010.

You can use brackets to control precedence – the order in which multiple criteria are evaluated within your search criteria. Normally, criteria joined by an AND operator are evaluated ahead of criteria joined by an OR operator. However, any criteria surrounded by brackets will be given priority and evaluated ahead of any other criteria.

In the following example....

...contacts would have to satisfy both the A and B criteria – or satisfy the C criteria alone – to be included in the results. If, however, you place brackets as shown here...

...then contacts would have to satisfy either the B or C criteria, as well as the A criteria.

Filtering using multi-option fields

When filtering using multi-option fields, you can reference individual choices using either the option ID or the option label.

Multi-option fields include those with a field type of Choice (radio buttons, dropdown, radio buttons with extra charge) or MultipleChoice (multiple choice, multiple choice with extra charge).

For each field, the field type is returned by the ContactFields API call. For multi-option fields, the ID and label is returned for each field as well under AllowedValues.

In the following example, a dropdown Membership status field has values of either ActiveLapsedPendingNew, or PendingRenewal.

If you wanted to limit search results to contacts with a Membership status of Lapsed, you could use either the option ID of 2, or the option label of Lapsed. To indicate whether you are referencing the option using the ID or the label, you include a suffix of either .Id or .Label following the field name. To limit search results to contacts with a Membership status of Lapsed using the option ID, your filter criteria would appear as follows:

To limit search results using the label ID, your filter criteria would look like this:

If the field name contains spaces or special characters, you must enclose the field name and the suffix within quotation marks. For example:

Selecting API response fields

Using the $select parameter, you can control which fields are returned by the Contacts API call.

$select syntax

where {fieldlist} is a list of fields to be included in the results. When you use the $parameter, only fields specified by the parameter will be included in the search results.

Example:

The field names correspond to the fields returned by the ContactFields API call, not the field names that appear in Wild Apricot. Multiple field names are separated by commas, and field names with spaces or special characters are enclosed in single quotation marks.

 
Wild Apricot Inc. 144 Front Street West Suite 725, Toronto, Ontario, Canada M5J 2L7