Due to PCI compliant reasons we're going to turn off support for TLS v1.0 on all of our servers.
Please check/update you API implementations to support TLS v1.2 until 29.06.2018

REST API Participants

From XING Events Developer Documentation
Jump to: navigation, search

This page contains information about all properties and methods regarding a participant.
You can understand a participant object as the aggregation of the payment and ticket object.
To get all participant objects of an event, see Enumerate participants in the event object.

Properties

Attributes: R - accessible in read requests W - accessible in write (update) requests C - accessible in create requests

Property
Type
Attributes Description
id
Integer
R--
The internal id of this object.
eventId
Integer
R--
The internal id of the event this participant is registered for.
status
String
R--
The status of the participant.
paymentId
Integer
R--
The internal id of the associated payment.
salutation
Integer
RWC
The salutation of the participant. The values are: 0 = Mr. 1 = Ms. 2 = Mrs.
title
String
RWC
The title of the participant (e.g. Dr., Prof., etc.).
firstName
String
RWC
The first name of the participant.
Mandatory for create call.
lastName
String
RWC
The last name of the participant.
Mandatory for create call.
email
String
R-C
The email address of the participant.
Mandatory for create call.
company
String
RWC
The company the participant provided if the field is requested in the event.
pictureLink URL R(W)-
Link to the picture of the attendee. This property is only send if the the "Attendee image" field is activated in the event and the buyer uploaded an image in the buying process. You can attach a "width=x" and "height=y" parameter to the provided URL to get the image resized to your needs (in pixels). If the requested size is bigger then the originally uploaded file, the returned image will have the original size.
To upload an image, see Image upload
language
Language
R-C
In which language did the buyer make his purchase.
doubleOptIn String
RWC
Gets or sets the double opt-in status of the participant.
"FALSE": User did not select the checkbox (or double opt-in field wasn't available in the shop)
"WAITING": User ticked the checkbox but didn't click the link in the mail yet.
Date/Time value: If the user clicked on the link (did the full double opt-in) this value represents the date and time of that interaction.
displayIdentifier
String
R--
The public identifier of the ticket.
identifier
String
R--
The identifier used in the barcode of the ticket.
discountCode
String
R-C
The discount code used in the buying process.
registrationDate Date
R--
The date the participant registered/bought the ticket.
paidDate Date
R--
The date the ticket was marked as paid. Null if the ticket is still unpaid.
cancelled Date
R--
The date the ticket of this participant got cancelled or null.
paymentStatus String R--
The current status of the payment for the participant's ticket. Details
paymentType String R--
The payment type used to buy this ticket. Details
buyerAddress BuyerAddress
R(W)(C)
The billing address used while buying the ticket for this participant.
To update the buyer address, use the /payment/<payment_id>/address/buyer function (see address/buyer). In the create call set the address by providing the parameters street, street2, zipCode, city, state, country.
buyerUserData Array of
UserData
RWC
This array holds user data objects provided for the purchase of this ticket. User data objects hold additional values, which are asked when a user buys a ticket. These fields can be added to any event by the host. To set a value of this fields you need to add dataId=value as parameter to the update call.
userData Array of
UserData
RWC
This array holds user data objects provided for this specific ticket. User data objects hold additional values, which are asked when a user buys a ticket. These fields can be added to any event by the host. To set a value of this fields you need to add dataId=value as parameter to the update call.
tickets Array of
TicketInformation
R--
This array holds all tickets of this participant. Only in the case of the deprecated registration events this array can contain more than one item, which in that case represent the categories the user selected.
products Array of
ProductInformation
R--
This array holds all products of this participant. This includes the products chosen on payment and on ticket level.
checkInHistory Array of
CheckInAction
R--
This array holds all devaluation/reset (check in/check out) actions that happened to the ticket of this participant.
invoiceLink URL R--
Link to the invoice of the participant's payment (PDF file).
ticketLink URL R--
Link to the ticket of the participant (PDF file).
badgeLink URL R--
Link to the badge of the participant (PDF file).
badgePngLink URL R--
Link to the badge of the participant (PNG file).
editUrl URL R--
Link to the page where the participant's data can be edited.

Methods

Read

Call GET /api/participant/<id>
Description This request will return the participant object with the specified internal id. The response contains all properties marked with R.
Response {"participant":{"firstName": ...},"success":true}.
Errors See General Errorcodes.


Update

Call POST /api/participant/<id>
Parameters All properties marked with W.
Description This request will update the properties of the participant with the internal id <id>. Only properties which are provided as parameters will be updated. To update userData or buyerUserData fields you need to add dataId=value as parameter (e.g. <userFieldId>=foo&<otherUserFieldId>=bar). Sadly updating a user field of type "address" is currently not available.
Response {"success":true}.
Errors See General Errorcodes.


Create

Important information: To use this call you need to sign a "data processing agreement". Please contact our support or your account manager if you didn't sign this agreement yet. As long as no "data processing agreement" is signed this call will return the error: com.amiando.api.rest.DataProcessingAgreementMissing

Call POST /api/event/<eventID>/participant/create
Parameters ticketCategoryId — The ticket category of the new generated ticket (mandatory)

acceptedTermsAndConditions — Must be set to "1" or "true" to signal that you are allowed to do this import in the name of the person you provided in the payment (mandatory).
disableEmails — Should the ticket mail be send to the new participant (default: true)
applicationData — Internal data for the created payment (Click here for detailed information)
distributionChannel — To override the default distribution channel for your statistics (default: CHANNEL_API_V1)
street — Street of the "buyer"
street2 — Additional street of the "buyer"
zipCode — Zip code of the "buyer"
city — City of the "buyer"
state — US state of the "buyer"
country — Country of the "buyer"
telephone — Telephone number of the "buyer"
vatId — Vat number of the "buyer" (printed on the invoice)
referenceNo — Reference number of the "buyer" (printed on the invoice)
All properties marked with C.

Description This request will create a new participant/ticket in your event. The buyer information will be filled with the same name/email as the participant. To update userData or buyerUserData fields you need to add dataId=value as parameter (e.g. <userFieldId>=foo&<otherUserFieldId>=bar). Sadly updating a user field of type "address" is currently not available.
If the ticket costs money, the amount will be listed in your revenues as income but deducted as "direct payment" as we didn't receive the money and we assume you collected it on your own. You can also apply a discount code with this call to reduce the amount to your wish (e.g. to 0) and with that exclude the payment amount from your revenue statistics.
Response {"success":true}.
Errors See General Errorcodes.

Image upload

Call POST /api/participant/<id>/uploadPicture
Parameters Content-Type (Header value): Set a valid image content type in the header ("image/jpeg" or "image/png")
Post the file content as a binary stream with the request.
Description This request will update the attendee's picture.
Sample call:
curl -i "https://www.xing-events.com/api/participant/{participantId}/uploadPicture?apikey={apiKey}&version=1" -H "Content-Type: image/jpeg" --data-binary @path/to/file.jpg
Response {"success":true, "pictureURL":"<URL to uploaded picture>"}
Errors com.amiando.Event.InvalidContentType

See General Errorcodes.

Check

Call POST /api/participant/<id>/check
Description This request will check (devaluate) the provided tickets and/or products of this participant.
Parameters all parameters are optional:
categories — List of ticket categories to devaluate (e.g. categories=123,124,125)
products — List of productDefinitionOptionId's to devaluate (e.g. products=123,124,125)
tool — The name of the tool calling this API (e.g. "Company Check-In iOS v2.5")
device — A name of the device that is calling this API (e.g. "iPad 1234", "Hostess A", "Entrance A", "Main Entrance")
source — The source how the ticket identifier was identified. Valid values are: SEARCH, PASSBOOK, MOBILE_TICKET, ETICKET, PAPER_TICKET
checkedDate — The date/time the ticket/product was devaluated (e.g. checkedDate=2010-01-01T00:00:00). If this parameter is not provided, the date will be set to the date/time of this call.
Response {"success":true}.
Errors com.amiando.api.rest.InvalidDevaluationSource

com.amiando.api.rest.InvalidParam
General Errorcodes
No error will be thrown if one or all provided categories or products are not available for this participant.

Reset

Call POST /api/participant/<id>/reset
Description This request will reset the devaluation status of the provided tickets and/or products of this participant.
Parameters all parameters are optional:
categories — List of ticket categories to devaluate (e.g. categories=123,124,125)
products — List of productDefinitionOptionId's to devaluate (e.g. products=123,124,125)
tool — The name of the tool calling this API (e.g. "Company Check-In iOS v2.5")
device — A name of the device that is calling this API (e.g. "iPad 1234", "Hostess A", "Entrance A", "Main Entrance")
source — The source how the ticket identifier was identified. Valid values are: SEARCH, PASSBOOK, MOBILE_TICKET, ETICKET, PAPER_TICKET
checkedDate — The date/time the ticket/product was reset (e.g. checkedDate=2010-01-01T00:00:00). If this parameter is not provided, the date will be set to the date/time of this call.
Response {"success":true}.
Errors See General Errorcodes.
No error will be thrown if one or all provided categories or products are not available for this participant.


Status

The status property indicates the current status of the participant.
You shold only interpret participants with the first status ("accepted") as attendees going to the event.
Possible values are:

Status
Description
com.amiando.participant.status.accepted
This participant is registered to the event (may or may not have paid yet).
com.amiando.participant.status.cancelled
The ticket of this participant got cancelled
com.amiando.participant.status.onHold
User pre-registered to the event (awaiting acceptance/decline of organizer).
com.amiando.participant.status.acceptedByHost
User pre-registered to the event and was accepted by the organizer but did not finalize his registration yet.
com.amiando.participant.status.declinedByHost
User pre-registered to the event and was declined by the organizer.
com.amiando.participant.status.invited
User got invited to participate via an email campaign, but did not respond yet.
com.amiando.participant.status.imported
This potential participant was imported into the event but the particpant did not yet confirm the participitation.
com.amiando.participant.status.declined
The user declined coming to the event (was only possible in deprecated registration events).

Ticket Information

The tickets property returns an array of TicketInformation objects. These objects provide the id of the tickets and information about the current check state.
These are the properties of this objects:

Property
Type
Description
id
Integer
The internal id of this ticket.
ticketCategoryId
Integer
The internal id of the ticket category of this ticket.
ticketCategoryName
String
The name of the ticket category of this ticket.
checked
Boolean
Is the current state of the ticket, checked or unchecked.
checkedDate
Date
The last date/time the check state was changed.
checkedDevice
String
The device name used to set the last check state (e.g. "Entrance A", "Entrance B").

Product Information

The products property returns an array of ProductInformation objects. These objects provide the id of the products and information about the current check state.
These are the properties of this objects:

Property
Type
Description
id
Integer
The internal id of this product.
productDefinitionId
Integer
The internal id of this product definition the user selected, so which type of product he bought (see id in the Product Definitions object).
productDefinitionOptionId
Integer
The internal id of this product option the user selected, so the actual product he bought (see productDefinitionOptionId in the Product Definitions object).
checked
Boolean
Is the current state of the product, checked or unchecked.
checkedDate
Date
The last date/time the check state was changed.
checkedDevice
String
The device name used to set the last check state (e.g. "Entrance A", "Entrance B").
cancelledDate
Date
If the product is cancelled, the date of the cancellation is provided here.

CheckInAction

A CheckInAction is an entry that is added to this array if the ticket of the participant is devaluated (check-in) or reset (check-out).

Property
Type
Description
action
String
The type of action that happened: "DEVALUATED" (for a check-in), "RESET" (for a check-out)
ticketId
Integer
If the ticket itself got devaluated/reset (and not an additional product on the ticket), the ticketId itself is provided.
productId
Integer
If an additional product on the ticket got devaluated/reset (and not the ticket itself), the ID of the corresponding product is provided here.
date
Date
The date/time the action was done.
device
String
The name of the device that triggered this action (e.g. the name set in EasyEntry like "Main Entrance")
tool
String
The application that triggered this action (e.g. "EasyEntry android v.3.2.0")

Buyer Address

The buyerAddress provides the address that was provided as billing address during the purchase of the ticket for this participant.

Property
Type
Description
salutation
Integer
The salutation of the buyer. The values are: 0 = Mr. 1 = Ms. 2 = Mrs
title
String
The buyer's title (e.g. "Dr.", "Prof.", ...)
firstName
String
First name of the buyer.
lastName
String
Last name of the buyer.
email
String
E-Mail address of the buyer.
company
String
Company of the buyer.
street
String
Street of the buyer.
zipCode
String
Zip code of the buyer.
city
String
City of the buyer.
country
Country
Country of the buyer.
telephone
String
Telephone number of the buyer.
vatId
String
VAT ID of the buyer.
REST API Contents
Getting Started Get your API key Overview Formats Errors
Data Types Event Participant Payment Ticket
Ticket Categories ProductDefinition Products CodeDefinition
TicketShop Addresses Ticket Types Payment Types
BankAccount UserDataDefinition UserData User
Partner ApiKey
Data Synchronization Sync Interface