Home

Download this help site
(PDF 82MB)

Download

Contacts API V2 call

Icon

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.

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.

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. For more information, see  Selecting response fields  (below). As well, you can retrieve contact records in sets or pages. For more information, see Paging (below).

Icon

Archived contacts are included in your search results unless you explicitly filter them out using the $filter=Archived eq false filter. For more information, see Filtering the results.

Retrieving the number of contacts

You can use a Contacts API call to retrieve the number of contact records in your Wild Apricot database. 

Syntax

Icon

Each API call must include an authentication information that verifies your account and prevents others from accessing your data. For more information, see Authenticating API access from a 3rd-party server or application or Authenticating API access from a Wild Apricot site page.

Example

The call is executed synchronously. The number of contacts will be returned in a Count field.

Sample response

Retrieving information for a specific contact

Syntax

Example

Retrieving information for the current contact

Syntax

Example

Retrieving information for all contacts

You can retrieve information for all contacts either synchronously or asynchronously. If you perform the call synchronously, then the results are immediately displayed. If you perform the call asynchronously, then retrieving the information 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.

Synchronous search request

Syntax

Example

Asynchronous search request

Syntax

Example

Asynchronous results request

Syntax

Example

Parameters

The following parameters are used within the Contacts API call:

Variable

Description

{baseAPIaddress}

The base address of the API. For more information, see API access options .

{version}The version number of the API. Versions 2 and 2.1 are supported for this call. If you want to retrieve picture fields along with other information, you must specify v2.1 as the API version. 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 unique identifier for 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.

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

Icon

Each API call must include an authentication token that authenticates your account and prevents others from accessing your data. For more information, see API V2 authentication.

The following parameters are optional:

Variable

Description

For more information, see...

$asyncControls whether the API call is perform asynchronously.Retrieving information for all contacts

$filter

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

Filtering the results

$select

Controls which fields are returned in the Contacts API call.

Selecting response fields

Response fields

Search request

In the first and second stages of an asynchronous 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 an asynchronous contact search – and in the first and only stage of a synchronous 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.

DisplayNameThe full name of the contact.
OrganizationThe organization to which the contact belongs.

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.

MembershipEnabledIndicates whether the contact is a member. A value of false indicates that the contact is a not a member or is a suspended member.

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, its system code, and its value for this contact are returned. The system code is a unique field identifier that can be used instead of the field name to identify the field. 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

 Click here to expand/collapse

Sample XML response

 Click here to expand/collapse

Filtering the results

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.

Icon

Filtering your search results can significantly reduce server response time.

 Click here to expand/collapse

You can filter using any field returned by the ContactFields API V2 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('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:

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.

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:

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:

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. 

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

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.

Retrieving a list of contact IDs

You can retrieve a list of contact IDs by submitting a synchronous search request and including the idsOnly parameter.

Syntax

Example

Creating a new contact record

You can use a Contacts API call to create a new contact record. 

Syntax

Parameters

Field

Description

Id

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

FirstName

The contact's first name.

LastName

The contact's last name.

Email

The contact's email address.

PasswordThe contact's password.

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.

MembershipEnabledIndicates whether the contact is a member. A value of false indicates that the contact is a not a member or is a suspended member.

Status

The status of the contact's membership. Possible values are Active, Lapsed, PendingNew, PendingRenewal, and PendingLevelChange. The status can only be updated 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. To identify the field, you can use FieldName or SystemCode. SystemCode is a unique field identifier and can be used instead of FieldName for more accurate field identification. If both FieldName and SystemCode are defined, the field will be searched first by SystemCode and then by FieldName, (where there are no fields with the specified SystemCode). If only FieldName is defined and there are two fields that use it – system and custom – then only the system field will be updated.

RecreateInvoiceIndicates whether an invoice needs to be created. Default value is true.
Icon
  • The contact ID should be 0 or should not be specified.
  • There are no required fields.

Example

An HTTP 400 error will be returned if:

  • Any of the fields include invalid data
  • The billing plan contact limit is reached

The error description will indicate the nature of the error. For more information, see API V2 status codes.

Updating contact records

You can update an existing contact record using a Contacts API call.

Syntax

Parameters

Field

Description

Id

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

FirstName

The contact's first name.

LastName

The contact's last name.

Email

The contact's email address.

PasswordThe contact's password.

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.

MembershipEnabledIndicates whether the contact is a member. A value of false indicates that the contact is a not a member or is a suspended member.

Status

The status of the contact's membership. Possible values are Active, Lapsed, PendingNew, PendingRenewal, and PendingLevelChange. The status can only be updated 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. To identify the field, you can use FieldName or SystemCode. SystemCode is a unique field identifier and can be used instead of FieldName for more accurate field identification. If both FieldName and SystemCode are defined, the field will be searched first by SystemCode and then by FieldName, (where there are no fields with the specified SystemCode). If only FieldName is defined and there are two fields that use it – system and custom – then only the system field will be updated.

RecreateInvoiceIndicates whether an invoice needs to be created. Default value is true.
Icon
  • The contact ID must be specified. All other contact fields are optional.
  • For multi-option fields – those with a field Type of Choice (radio buttons, dropdown, extra charges radio buttons) or MultipleChoice (multiple choice, extra charge multiple choice) – you can use reset the field value by setting the Label to null (and not specifying the field ID).
  • If you want to update picture fields, you must specify v2.1 as the API version.

Example

Updating membership levels

You can update a contact's membership level using a Contacts API call. If you are assigning a contact to a membership bundle, you can specify the bundle ID and designate the contact as a bundle administrator.

Icon

You can retrieve bundle IDs using the Bundles API V2 call.

Syntax

Icon
  • MEMBER_ROLE can be either Bundle administrator or Bundle member. If not specified, it defaults to Bundle member.
  • If the contact is already a bundle administrator, you can only change their level to another bundle level. All members within the original bundle will be moved along with the bundle administrator.
  • If you move a contact to a bundle level without specifying the bundle ID, then the contact automatically becomes a bundle administrator.
  • If you specify the bundle ID when you move a contact to a bundle level, their role is derived from the Member role field.

Example

Deleting an archived contact

Syntax

Example