Using the Contacts API, you retrieve or update contact information, and add contacts to your database. You can retrieve a detailed list of contacts, a list of contact IDs, or details about a particular contact. You can retrieve the contact list synchronously or asynchronously.

Wild Apricot's API is intended for use by developers with technical expertise. If you need assistance, we provide support via email or through our Developers forum.

Responses can be filtered so that only those records that match the filter criteria will be retrieved. Filtering your search results can significantly reduce server response time. You can also control which fields are included in the results. As well, you can retrieve contact records in sets or pages.

Archived contacts are included in your search results unless you explicitly filter them out using the $filter=Archived eq false filter.

Contacts API functions

The Contacts API call supports the following functions. To view the Swagger documentation, click the appropriate function below.

Specifying filter criteria

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

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

GET https://api.wildapricot.org/[version]/Accounts/[accountID]/Contacts?$filter=[filterCriteria]

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

Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts?$filter=Balance gt 100

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('field', 'value')

String

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

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:

$filter='Job title' ne NULL

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

$filter='Profile last updated' ge 2013-06-25

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...

$filter='State/Prov' eq 'California' AND Organization eq 'Google'

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

In this example...

$filter=Total donated'gt 500 OR 'Member since' ge 2010-01-01

...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....

$filter=A and B or C

...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...

$filter=A and (B or C)

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

Single quotation marks escaping

If a field name contains a single quotation mark, character escaping should be applied to $filter and $select parameters using the escape sequence \'. For example, to filter using a custom field with a name of my custom' field, you would use the following approach:

$filter='my custom\' field' eq 'some value'&$select=id,'my custom\' field

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 Active, Lapsed, PendingNew, or PendingRenewal.

"FieldName": "Membership status",
"Type": "Choice",
"IsSystem": true,
"Access": "AdminOnly",
"AllowedValues": [
    {
        "Id": 1,
        "Label": "Active"
    },
    {
        "Id": 2,
        "Label": "Lapsed"
    },
    {
        "Id": 20,
        "Label": "PendingNew"
    },
    {
        "Id": 3,
        "Label": "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:

$filter='Membership status.Id' eq 2

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:

$filter='Optional extras.Label' eq ‘Newsletter’

Paging

Using the $skip and $top parameters, you can retrieve contact records in sets or pages. You use the $top parameter to specify the maximum number of records to be returned, and the $skip parameter to specify the number of records to skip. The $skip parameter is incremented each call to return the next set or page of records.

Paging can be applied both in synchronous and asynchronous search results. In a synchronous call, the paging parameters are specified along with the $filter and $select parameters. In asynchronous calls, these parameters are specified when retrieving the result, together with the resultId parameter.

Example

You want to retrieve records for the 50 contacts who reside in California, using an application that can only process 20 records at a time. Using the following calls, the application retrieves the first set of 20 records, then a second set of 20, and finally, the remaining 10 records.

https://api.wildapricot.org/v2/Accounts/58293/Contacts?$async=false&$filter='State/Prov' eq 'California'&$skip=0&$top=20
https://api.wildapricot.org/v2/Accounts/58293/Contacts?$async=false&$filter='State/Prov' eq 'California'&$skip=20&$top=20
https://api.wildapricot.org/v2/Accounts/58293/Contacts?$async=false&$filter='State/Prov' eq 'California'&$skip=40&$top=20

In this example, the $top specifies the maximum number of records to retrieve (20), and the $skip parameter is incremented from 0 to 20 to 40 to skip the records retrieved by the previous call(s).

Selecting response fields

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

$select syntax

GET https://api.wildapricot.org/v2/Accounts/[accountID]/Contacts?$select=[fieldlist]

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:
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts?$select='Member ID', 'Membership status', 'First name', 'Last name'

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.