Home

Download this help site
(PDF 82MB)

Download

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

You can use the Events API call to retrieve information about events, and to create, update, or delete an event. You can retrieve information for all events, and just for a specific event. You can also use the Events API to retrieve the number of events.

Retrieving the number of events

Syntax

Example

The number of events will be returned in a Count field.

Retrieving information for all events

Syntax

Example

The events list request can contain the following optional query string parameters:

  • includeEventDetails – if it set to true, event details will be retrieved for each event. 
  • idsOnly – specify without a value to retrieve only a list of event identifiers

Retrieving information for a particular event

Syntax

Example

Retrieving specific events 

You can retrieve information for specific events by specifying a list of events IDs. Only events with the specified IDs will be retrieved. 

Syntax 

 Example

Retrieving event tags 

You can retrieve a list of event tags currently in use. 

Syntax 

 Example

The result will be an array (e.g. [ "tag1", "tag2", "tag3" ] )

Parameters

The following parameters are used within the Events API call:

Variable

Description

{baseAPIaddress}

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

{accountID}

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

{eventID}The unique identifier of an event. Event IDs are returned by the Events API call.
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.

Response fields

When retrieving information for one or more event, the Events API call retrieves the following information for each event.

Field

Description

StartDate

The time and date the event is scheduled to begin.
EndDateThe date the event ends.
StartTimeSpecifiedIndicates whether the start time was specified.
EndTimeSpecifiedIndicates whether the end time was specified.
LocationThe location of the event.
RegistrationEnabledIndicates whether registration has been enabled for this event.
HasEnabledRegistrationTypesIndicates whether any registration types have been enabled for this event.
RegistrationsLimitThe limit on the number of registrations.
PendingRegistrationsCountThe number of pending registrations.
ConfirmedRegistrationsCountThe number of confirmed registrations
CheckedInAttendeesNumberThe number checked-in attendees.
TagsAny tags – labels used to categorize events – assigned to the event.
AccessLevelThe access level for this event. Possible values: Public, AdminOnly, Restricted.
IDThe unique identifier of the event.
URLThe address of the API call for this event.
NameThe name assigned to the event.

When retrieving information for a specific event, the Events API also displays the following information, grouped under a Details field:

Field

Description

DescriptionHtmlThe HTML of the event description.
PaymentInstructionsThe payment instructions entered for this event.
TimeZoneThe time zone for the event, including the zone ID, name, and offset.
RegistrationTypes

The registration types for this event. For each registration type, the following information is returned.

FieldDescription
IdThe unique identifier for this registration type.
UrlThe URL for this registration type.
EventIdThe unique identifier of the event to which this registration type belongs.
NameThe name assigned to the registration type.
IsEnabledIndicates whether registration has been enabled for this registration type.
DescriptionThe description assigned to the registration type.
BasePriceThe base price for the registration type.
GuestPriceThe registration price for guest registrations.
UseTaxScopeSettingsIndicates whether tax scope settings are being applied to this event.
AllowGuestRegistrationIndicates whether guest registrations have been enabled.
Availability

Indicates whether access to this event has been restricted. The possible values are Everyone, MembersOnly, and CodeRequired.

RegistrationCodeThe registration code for this event.
AvailableForMembershipLevelsThe membership levels to which registration is limited.
AvailableFromThe first date on which this membership level is available.
AvailableThroughThe final date on which this membership level is available.

MaximumRegistrantsCount

Maximum number of registrants for this registration type.
CurrentRegistrantsCountCurrent number of registrants for this registration type
EventRegistrationFields

For each registration field, the following information is returned.

FieldDescription
KindIndicates the type of field. Possible values are Common, Custom.
IsRequiredIndicates whether this is a required field that must be completed in order to register for this event.
AdminOnlyIndicates whether the field is accessible to administrators only.
IsSystemIndicates whether the field is a system field.
DescriptionThe field description (for system fields only).
OrderThe position of the field within the field list.
FieldNameThe name assigned to the field.
Type

The field type. Possible values and the corresponding field types as they appear in Wild Apricot are:

ValueField type
BooleanRules and terms, various system fields
ChoiceRadio buttons, dropdown, radio buttons with extra charge
DateTimeDate
MultipleChoiceMultiple choice, multiple choice with extra charge
CalculatedExtraChargeExtra charge calculation
NumberVarious system fields
StringText, multiline text
AllowedValuesFor multi-option fields – those with a field Type of Choice (radio buttons, dropdown, radio buttons with extra charge) or MultipleChoice (multiple choice, multiple choice with extra charge) – the ID and label of each individual option is returned.
ExtraCharge

For extra charge calculation fields, the following information is displayed:

FieldDescription
MultiplierTypeIndicates whether the multiplier is the unit cost (ItemPrice) or percentage (Percentage).
MultiplierThe decimal value of the multiplier.
MinAmountThe minimum number of items for ItemPrice multiplier types
MaxAmountThe maximum number of items for ItemPrice multiplier types
MinChargeThe minimum resulting charge for Percentage multiplier types
MaxChargeThe maximum resulting charge for Percentage multiplier types
SystemNameThe internal system name used to refer to this field (system fields only).
TotalPaidThe total sum paid for all registrations for this event.
TotalDueThe total sum due but not yet paid for registrations for this event.
AccessControl

Indicates who can view this event either on an event calendar or via a direct link. Depend on the event's access level, the following fields may be returned.

FieldDescription
AccessLevelPossible values: Public, AdminOnly, Restricted
AvailableForAnyLevelIf AccessLevel is set to Restricted, indicates whether access is enabled for all membership levels.
AvailableForLevelsIf AvailableForAnyLevel is false, lists the ID and URL of membership levels that have been granted access.
AvailableForAnyGroupIf AccessLevel is set to Restricted, indicates whether access is enabled for all member groups.
AvailableForGroupsIf AvailableForAnyGroup is false, lists the ID and URL of member groups that have been granted access.
GuestRegistrationSettings

Grouped under here are the following fields:

FieldDescription
EnabledIndicates whether guest registrations are enabled.
CreateContactMode

Indicates the circumstances under which contact records are created when creating guest registrations. The possible values are:

  • NeverCreateContact
  • CreateContactForAllGuests
  • CreateContactForGuestsWithEmail
MultipleRegistrationAllowedIndicates whether visitors can register multiple times for the same event.
OrganizerThe contact ID and URL of the event organizer
SendEmailCopyIndicates whether copies of event emails are sent to the event organizer.
PaymentMethodIndicates the payment method for this event. Possible values: Undefined, OnlineAndOffline, OfflineOnly, OnlineOnly
RegistrationConfirmationExtraInfoExtra information to be included in the registration confirmation email.
RegistrationMessageInformation to be displayed above the Register button on the event details screen.
WaitlistBehaviourIndicates the waitlist behavior. Possible values: Disabled, Undefined, RequestNameAndEmail, RequestContactInformation, RequestRegistrationInformation
AttendeesDisplaySettings

Indicates whether and how a list of event registrants appears for the event on the event calendar and in the event details.

FieldDescription
VisibleToIndicates who can see the list of event registrants. Possible values: Public, Members, Nobody
ShowPendingAttendeesIndicates whether pending registrations are included in the registrants list.
Sessions

For each session in a multi-session event, the following fields are returned:

FieldDescription
IDThe event session ID.
TitleThe title of the event session.
StartDateThe starting date of the event session.
EndDateThe end date of the event session.

Sample JSON response

Sample XML response

Filtering the results

You can filter the results of the Events API call so that only those events that match the filter criteria will be included. For example, you might want to retrieve information only about upcoming events, or events between certain dates.

Within your filter criteria, you can use relational operators to include ranges of events, 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 events between January 15th, 2015 and June 15th, 2015 will be included in the results.

Filter fields

You can filter events using the following fields:

FieldDescriptionSupported operators
IDA list of event IDs.in
NameThe name of the event.eq, substringof
IsUpcomingIndicates whether the event has yet to take place.eq
TagsThe labels used to categorize events.in
StartDateThe start date of the event (using the yyyy-mm-dd date format)eq, gt, ge, lt, le
EndDateThe end date of the event (using  the  yyyy-mm-dd  date format)eq, gt, ge, lt, le
RegistrationEnabledIndicates whether registration has been enabled for the event.eq
TextIndexReturns events that contain the specified string within the event title, description, location, start date or event tagsubstringof

Relational operators

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

Operator

Description

Fields

Example

eq

Equal to

Name, IsUpcoming, StartDate, EndDate, RegistrationEnabled

$filter=RegistrationEnabled eq true

gt

Greater than

StartDate, EndDate

$filter=StartDate gt 2015-01-15

ge

Great than or equal to

StartDate, EndDate

$filter=EndtDate ge 2015-01-15

lt

Less than

StartDate, EndDate

$filter=StartDate lt 2015-06-15

le

Less than or equal to

StartDate, EndDate

$filter=End tDate le 2015-01-15

inIn list of valuesTags$filter=Tags in [social, training]

substringof

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

Name, TextIndex

$filter=substringof('Name', 'Annual')

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

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

...events must have registration enabled and must be taking place after January 15, 2015 to be included in the results.

In this example...

...events will included in the search results if they have the word "training" in their name or their tags.

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

...events 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 events would have to satisfy either the B or C criteria, as well as the A criteria.

Sorting the results

Using the $sort parameter, you can control the order in which the results of the Events API are sorted.

Syntax

where {sortCriteria} is one of the following:

CriteriaDescription
StartDate ascSorted by event start date, in ascending order
StartDate descSorted by event start date, in descending order
StartSession ascSorted by first session date, in ascending order

Example:

Paging

Using the $skip and $top parameters, you can retrieve event 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.

Example

You want to retrieve records for the 50 events for which registration has been enabled, 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).

Updating event details

You can update event details for an existing event using an Events API call.

Syntax

where eventField is a field returned by the Events API call.

Icon
  • The event ID must be specified and must match the event ID in the URL.
  • If you update the RegistrationsLimit value, you have to provide a value with each future update, or else it will be reset to its default value of null.
  • Read-only fields: HasEnabledRegistrationTypes, PendingRegistrationsCount, ConfirmedRegistrationsCount, CheckedInAttendeesNumber, AccessLevel

Example

An HTTP 400 error will be returned if the event ID is invalid or doesn't match the event ID in the URL.  For more information, see  API V2 status codes .

Creating a new event

You can use an Events API call to create a new event. 

Syntax

 where eventField is a field returned by the Events API call.

Icon

Required fields: StartDate, Name.

Read-only fields: HasEnabledRegistrationTypes, PendingRegistrationsCount, ConfirmedRegistrationsCount, CheckedInAttendeesNumber, AccessLevel

Example 

If successful, the call returns the new event ID. If unsuccessful, it returns HTTP 400. 

Deleting an event

You can use an Events API call to delete an event. 

Syntax 

Example 

If the call is successful, it returns HTTP 200 Success. If it is unsuccessful, it returns HTTP 400 bad request. 

  • No labels