Contacts admin API call

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. If you are not an experienced programmer, consider using Make (formerly Integromat) to build automated workflows with Wild Apricot.

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.

• Retrieve information for a specific contact
• Retrieve information for the current contact
• Retrieve information for multiple contacts using filter criteria
• Create a new contact record
• Update a contact record
• Delete an archived contact

Filtering the results

You can filter the results of a multiple 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 criteria.

$filter syntax

GET
https://api.wildapricot.org/{version}/Accounts/{accountID}/Contacts?apikey={APIkey}&$filter={filterCriteria}

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

Example:

GET
https://api.wildapricot.org/v1/Accounts/58293/Contacts?apikey=rktud7anqouibtdm1d4yhob9dgy&$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.

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.

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

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’