Follow

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

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.

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
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Contacts?$count
Each API call must include an authentication information that verifies your account and prevents others from accessing your data. For more information, see API access options.
Example
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts?$count

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

Sample response
{
"Count": 1092
}

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
GET http://api.wildapricot.org/[version]/Accounts/[accountID]/Contacts/?$async=false&idsOnly
Example
GET http://api.wildapricot.org/v2/accounts/42353/Contacts/?$async=false&idsOnly

Retrieving information for a specific contact

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID[/Contacts/[contactID]
Example
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts/402784

Retrieving information for the current contact

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Contacts/me
Example
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts/me

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.

{
"ResultId": "ecbe4c97-f0bd-4dfb-a251-a9eeb196e637",
"ResultUrl": "https://api.wildapricot.org/v1/accounts/58293/Contacts/?resultId=ecbe4c97f0bd4dfba251a9eeb196e637",
"Requested": "2013-07-02T18:32:42.6450398+04:00",
"State": "Waiting",
"InitialQuery": {
"ObjectType": "Contact",
"FilterExpression": null,
"SelectExpression": null
}
}

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.

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
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Contacts?$async=false
Example
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts?$async=false

Asynchronous search request

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Contacts
Example
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts

Asynchronous results request

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Contacts?resultId=[resultID]
Example
GET https://api.wildapricot.org/v2/Accounts/58293/Contacts?resultId=ecbe4c97f0bd4dfba251a9eeb196e637

Parameters

The following parameters are used within the Contacts API call:

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 is returned by the Accounts API call.

contactID
The unique identifier for a contact. 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.

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

The following parameters are optional:

$async
Controls whether the API call is perform asynchronously. See Retrieving information for all contacts (above).

$filter
Filters the results of the Contacts API call so that only those records that match the filter criteria are included. See Filtering the results (below).

$select
Controls which fields are returned in the Contacts API call. See Selecting response fields (below).

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.

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.

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.

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.

DisplayName
The full name of the contact.

Email
The contact's email address.

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.

FirstName
The contact's first name.

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

LastName
The contact's last name.

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

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.

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

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.

Url
The address of the API call for this contact.

Sample JSON response

{
"FirstName": "Steve",
"LastName": "Andrews",
"Email": "steve@wildapricot.com",
"DisplayName": "Steve Andrews",
"ProfileLastUpdated": "2014-06-12T15:09:16-04:00",
"MembershipLevel": {
"Id": 29879,
"Url": "http://api.wildapricot.org/v2/accounts/42353/MembershipLevels/29879",
"Name": "Platinum"
},
"MembershipEnabled": true,
"Status": "Active",
"FieldValues": [
{
"FieldName": "Archived",
"Value": false
},
{
"FieldName": "Donor",
"Value": false
},
{
"FieldName": "Event registrant",
"Value": false
},
{
"FieldName": "Member",
"Value": true
},
{
"FieldName": "Suspended member",
"Value": false
},
{
"FieldName": "Notes",
"Value": "Notes updated during import on 27 May 2014.
Renewal processed on 30 May 2014 from 24 Apr 2014 until 24 Apr 2014."
},
{
"FieldName": "Event announcements",
"Value": true
},
{
"FieldName": "Member emails and newsletters",
"Value": true
},
{
"FieldName": "Email delivery disabled",
"Value": false
},
{
"FieldName": "Receiving emails disabled",
"Value": false
},
{
"FieldName": "Balance",
"Value": 0
},
{
"FieldName": "Total donated",
"Value": 0
},
{
"FieldName": "Registered for specific event",
"Value": null
},
{
"FieldName": "Profile last updated",
"Value": "2014-06-12T15:09:16-04:00"
},
{
"FieldName": "Profile last updated by",
"Value": 725060
},
{
"FieldName": "Creation date",
"Value": "2014-05-27T09:50:49-04:00"
},
{
"FieldName": "Last login date",
"Value": "2014-07-14T09:26:54-04:00"
},
{
"FieldName": "Terms of use accepted",
"Value": true
},
{
"FieldName": "Member ID",
"Value": 725060
},
{
"FieldName": "First name",
"Value": "Steve"
},
{
"FieldName": "Last name",
"Value": "Andrews"
},
{
"FieldName": "Organization",
"Value": "Keep It Wild"
},
{
"FieldName": "e-Mail",
"Value": "steve@wildapricot.com"
},
{
"FieldName": "Phone",
"Value": ""
},
{
"FieldName": "State/Province",
"Value": {
"Id": 137435,
"Label": "California"
}
},
{
"FieldName": "Member only",
"Value": null
},
{
"FieldName": "Member role",
"Value": "Individual"
},
{
"FieldName": "Member since",
"Value": "2013-07-10T20:00:00-04:00"
},
{
"FieldName": "Renewal due",
"Value": "2014-04-23T20:00:00-04:00"
},
{
"FieldName": "Membership level ID",
"Value": 29879
},
{
"FieldName": "Access to profile by others",
"Value": false
},
{
"FieldName": "Renewal date last changed",
"Value": null
},
{
"FieldName": "Level last changed",
"Value": null
},
{
"FieldName": "Bundle ID",
"Value": null
},
{
"FieldName": "Membership status",
"Value": "Active"
},
{
"FieldName": "Job title",
"Value": "Graphic designer"
},
{
"FieldName": "Website",
"Value": null
},
{
"FieldName": "Address",
"Value": null
},
{
"FieldName": "City",
"Value": "San Diego"
},
{
"FieldName": "Postal code",
"Value": null
},
{
"FieldName": "Province/State",
"Value": null
},
{
"FieldName": "Country",
"Value": "United States"
},
{
"FieldName": "Groups",
"Value": [
{
"Id": 507,
"Label": "Mailing list"
}
]
},
{
"FieldName": "Directory listing text",
"Value": null
},
{
"FieldName": "Member only 2",
"Value": null
}
],
"Id": 725060,
"Url": "http://api.wildapricot.org/v2/accounts/42353/Contacts/725060"
}

Sample XML response

<Contact xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.wildapricot.org">
<DisplayName>Steve Andrews</DisplayName>
<Email>steve@wildapricot.com</Email>
<FieldValues>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Archived</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">false</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Donor</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">false</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Event registrant</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">false</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Member</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">true</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Suspended member</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">false</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Notes</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Notes updated during import on 27 May 2014.
Renewal processed on 30 May 2014 from 24 Apr 2014 until 24 Apr 2014.</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Event announcements</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">true</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Member emails and newsletters</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">true</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Email delivery disabled</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">false</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Receiving emails disabled</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">false</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Balance</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:decimal">0</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Total donated</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:decimal">0</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Registered for specific event</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Profile last updated</FieldName>
<Value xmlns:d4p1="http://schemas.datacontract.org/2004/07/System" i:type="d4p1:DateTimeOffset">
<d4p1:DateTime>2014-06-12T19:09:16Z</d4p1:DateTime>
<d4p1:OffsetMinutes>-240</d4p1:OffsetMinutes>
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Profile last updated by</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:int">725060</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Creation date</FieldName>
<Value xmlns:d4p1="http://schemas.datacontract.org/2004/07/System" i:type="d4p1:DateTimeOffset">
<d4p1:DateTime>2014-05-27T13:50:49Z</d4p1:DateTime>
<d4p1:OffsetMinutes>-240</d4p1:OffsetMinutes>
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Last login date</FieldName>
<Value xmlns:d4p1="http://schemas.datacontract.org/2004/07/System" i:type="d4p1:DateTimeOffset">
<d4p1:DateTime>2014-07-14T13:26:54Z</d4p1:DateTime>
<d4p1:OffsetMinutes>-240</d4p1:OffsetMinutes>
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Terms of use accepted</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">true</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Member ID</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:int">725060</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>First name</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Steve</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Last name</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Andrews</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Organization</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Keep It Wild</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>e-Mail</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">steve@wildapricot.com</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Phone</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>State/Province</FieldName>
<Value i:type="ListItem">
<ExtraCost i:nil="true" />
<Id>137435</Id>
<Label>California</Label>
<Position i:nil="true" />
<SelectedByDefault i:nil="true" />
<Value i:nil="true" />
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Member only</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Member role</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Individual</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Member since</FieldName>
<Value xmlns:d4p1="http://schemas.datacontract.org/2004/07/System" i:type="d4p1:DateTimeOffset">
<d4p1:DateTime>2013-07-11T00:00:00Z</d4p1:DateTime>
<d4p1:OffsetMinutes>-240</d4p1:OffsetMinutes>
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Renewal due</FieldName>
<Value xmlns:d4p1="http://schemas.datacontract.org/2004/07/System" i:type="d4p1:DateTimeOffset">
<d4p1:DateTime>2014-04-24T00:00:00Z</d4p1:DateTime>
<d4p1:OffsetMinutes>-240</d4p1:OffsetMinutes>
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Membership level ID</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:int">29879</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Access to profile by others</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:boolean">false</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Renewal date last changed</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Level last changed</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Bundle ID</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Membership status</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Active</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Job title</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">Graphic designer</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Website</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Address</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>City</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">San Diego</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Postal code</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Province/State</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Country</FieldName>
<Value xmlns:d4p1="http://www.w3.org/2001/XMLSchema" i:type="d4p1:string">United States</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Groups</FieldName>
<Value i:type="ArrayOfListItem">
<ListItem>
<ExtraCost i:nil="true" />
<Id>507</Id>
<Label>Mailing list</Label>
<Position i:nil="true" />
<SelectedByDefault i:nil="true" />
<Value i:nil="true" />
</ListItem>
</Value>
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Directory listing text</FieldName>
<Value i:nil="true" />
</ContactField>
<ContactField>
<CustomAccessLevel i:nil="true" />
<FieldName>Member only 2</FieldName>
<Value i:nil="true" />
</ContactField>
</FieldValues>
<FirstName>Steve</FirstName>
<Id>725060</Id>
<LastName>Andrews</LastName>
<MembershipEnabled>true</MembershipEnabled>
<MembershipLevel>
<Id>29879</Id>
<Url>http://api.wildapricot.org/v2/accounts/42353/MembershipLevels/29879</Url>
<Name>Platinum</Name>
</MembershipLevel>
<Password i:nil="true" />
<ProfileLastUpdated xmlns:d2p1="http://schemas.datacontract.org/2004/07/System">
<d2p1:DateTime>2014-06-12T19:09:16Z</d2p1:DateTime>
<d2p1:OffsetMinutes>-240</d2p1:OffsetMinutes>
</ProfileLastUpdated>
<Status>Active</Status>
<Url>http://api.wildapricot.org/v2/accounts/42353/Contacts/725060</Url>
</Contact>

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.

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.

Creating a new contact record

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

Syntax
POST https://api.wildapricot.org/[version]/Accounts/[accountID]/Contacts/
{
"contactField": contactFieldValue,
"contactField": contactFieldValue,
...
}
Parameters

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.

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

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

RecreateInvoice
Indicates whether an invoice needs to be created. Default value is true.

There are no required fields. The contact ID should be 0 or should not be specified.
Example
POST https://api.wildapricot.org/v2/Accounts/58293/Contacts/
{
"FirstName": "Anatoly",
"LastName": "Fedyanin1",
"Email": "anfe@asd.com",
"MembershipLevel": {
"Id": 9144
},
"MembershipEnabled": true,
"Status": "Active",
"FieldValues": [
{
"FieldName": "Archived",
"Value": false
},
{
"SystemCode": "custom-123442", // You can use SystemCode instead of FieldName to identify fields
"Value": true
},
{
"FieldName": "Donor",
"Value": true
},
{
"FieldName": "Subscription source",
"Value": [
{
"Id": 1,
"Label": "First subscription form"
},
{
"Id": 827,
"Label": "SUbscription"
}
]
},
{
"FieldName": "Organization",
"Value": "wild-wild-apricot"
}
]
}

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

Updating contact records

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

Syntax
PUT [baseAPIaddress]/[version]/Accounts/[accountID]/Contacts/[contactID]
{
"Id": contactID,
"contactField": contactFieldValue,
"contactField": contactFieldValue,
...
}
Parameters

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.

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

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

RecreateInvoice
Indicates whether an invoice needs to be created. Default value is true.

  • 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
PUT https://api.wildapricot.org/v2/Accounts/58293/Contacts/725060
{
"Id": 725060,
"FirstName": "Steve",
"LastName": "Andrews",
"Email": "steve@test.com",
"MembershipLevel": {
"Id": 9144
},
"MembershipEnabled": true,
"Status": "Active",
"FieldValues": [
{
"FieldName": "Archived",
"Value": false
},
{
"SystemCode": "custom-123442", // You can use SystemCode instead of FieldName to identify fields
"Value": true
},
{
"FieldName": "Donor",
"Value": true
},
{
"FieldName": "Subscription source",
"Value": [
{
"Label": null
}
]
},
{
"FieldName": "Organization",
"Value": "Wild Apricot"
}
]
}

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.

You can retrieve bundle IDs using the Bundles API call.

Syntax
PUT [baseAPIaddress]/v2/Accounts/[accountID]/Contacts/[contactID]
{
"Id": CONTACT_ID,
"MembershipLevel":{
"Id": NEW_LEVEL_ID
},
"FieldValues":[
// optionaly bundle ID can be specified
{
"FieldName": "Bundle ID",
"Value": EXISTING_BUNDLE_ID
},
// optionaly bundle member role can be specified
{
"FieldName":"Member role",
"Value": "MEMBER_ROLE"
},
...
],
...
}
  • 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
PUT https://api.wildapricot.org/v2/Accounts/58293/Contacts/725060
{
"Id": CONTACT_ID,
"MembershipLevel":{
"Id": 257271
},
"FieldValues":[
// optionaly bundle ID can be specified
{
"FieldName": "Bundle ID",
"Value": 9086
},
// optionaly bundle member role can be specified
{
"FieldName":"Member role",
"Value":"Bundle administrator"
},
...
],
...
}

Deleting an archived contact

Syntax
DELETE [baseAPIaddress]/v2/Accounts/[accountID]/Contacts/[contactID]
Example
DELETE https://api.wildapricot.org/v2/Accounts/58293/Contacts/725060

0 Comments

Please sign in to leave a comment.

Search: WildApricot.com 

About results ( seconds) Sort by: 
Sorry, an error occured when performing search.