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

How-Tos

From XING Events Developer Documentation
Jump to: navigation, search

Update your CRM

In case you are using a CRM system to store your participants, you have multiple options to transfer the data the participants enter in your XING Events ticketshop to your CRM system. Each one has advantages/disadvantages and a different amount of complexity to setup the process. Simply choose whatever fits your needs.

Overview

integration advantages disadvantages
1. Export/Import - No complex setup
- No technical knowledge needed
- Manual work each time to update the data
2. Zapier - No complex setup
- No technical knowledge needed
- Your CRM might not be supported by Zapier
- Costs for the Zapier service might apply
- Data is only send once after the purchase, no update of data if changes are done afterwards
3. Webhook - Only small development needed - Data is only send once after the purchase, no update of data if changes are done afterwards
4. REST API/SYNC - Data is always up-to-date - Development needed

Guidance

1. Export/Import
All your participant's data can be exported as Excel-Files (or CSV files) in our adminitration area. Click on menu item "Data Export" and download the "List of tickets sold" and import that Excel file into your CRM systen.
We also provide "Own reports" where you can define what data exaclty you want to export. You can select what fields of the shop you are interested in, filter the data, order it, re-arange the columns and even make exports that span multiple events. Check with your CRM system what importing options it supports and select what you need.

2. Zapier
Our ticketing system also supports "Zapier". Zapier allows you to conenct two different systems through their API without any developing needs. Please see our Zapier documentation for more details.

3. Webhook
After each ticket purchase a "Webhook" can be executed. You write a script that interacts with the API of your CRM and our system will call this script after each purchase and sends all important information about the participant(s) to that script, so that you can forward the data to the API of your CRM.
Please see our Webhook documentation for more details.
We recommend to use the "server-call" webhook for this type of integration as those are more reliable.

4. REST API/SYNC
For the most fail-save and complete transfer of any data to your system, implement an integration with our REST API and the use of its SYNC functionality.
You need to do an initial loading of all existing participants using the "Enumerate participants" call for each of your events and afterwards activate the SYNC functionality. Now your system can every few minutes call our system to request if any new data is available (e.g. new ticket purchase, ticket cancellations, name changes, etc.) and update your CRM via its API accordingly.
For more information please read our ||XING_TicketingManager_REST_API|REST API documentation]].
The most important calls you need for this integration are probably:
Find user to get your account's user ID (you might want to do this call once and then store the User ID in your script)
Enumerate events to get all events of your account
Enumerate participants to get all the participants of each of your events
Participants object that shows you the data we provide for each participant
SYNC API to keep your system up to date and only load data that has changed

REST API Examples

Create an event with ticketing

If you have a lot of events, it can make sense to import them automatically from your system into our system. These are some sample calls to create and activate an event using the XING TicketingManager API.

To create an event you will need your user ID as this has to be set as the hostId of the event. If you do not have that ID already, call the user find method to get it (<yourUsername> is the email address you use to login to XING Events).
See User Find

 GET: 
 https://www.xing-events.com/api/user/find?apikey=<yourApiKey>&version=1&format=json&username=<yourUsername>
 Result: 
 {"ids":[<yourUserId>],"success":true}


Now you can create the event and provide different data describing the event.
See Event Create

 POST: 
 https://www.xing-events.com/api/event/create?apikey=<yourApiKey>&version=1&format=json&hostId=<yourUserId>&title=Awesome%20Event&country=DE&selectedDate=2016-01-01T08:00:00
 Result: 
 {"id":[<yourEventId>],"success":true}

In this sample we only provided the minimum of data required to create an event (hostId, title, country, selectedDate). Of course you should also have a look at all the other parameters you can provide to create an event and make use of them to fit the event to your needs. The call returned the ID of the new event you just created. Use that ID for the further steps.

To make your event beautiful, upload a logo and a banner image. For those a separate call is needed as the image data has to be streamed in the content of your request. Let's upload a banner image (must be 950 x 300 pixel):
See Logo upload
See Banner upload

 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/banner?apikey=<yourApiKey>&version=1&format=json
 Header value "Content-Type" must be set to "image/jpeg" or "image/png"
 The image itself needs to be send as a binary stream in the content of the request
 Result: 
 {"success":true}

This is an example using curl:

 curl -i "https://xing-events.com/api/event/<yourEventId>/banner?apikey=<yourApiKey>&version=1&format=json" -H "Content-Type: image/jpeg" --data-binary @path/to/file.jpg

To set values related to payment information, we need to update the ticketshop object of the event (In this sample: 19% VAT and currency set to EUR).
See TicketShop Update

 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/ticketShop?apikey=<yourApiKey>&version=1&format=json&salesTax=1900&currency=EUR
 Result:
 {"success":true}

Again, this call provides many more parameters, look them up in the documentation and add the ones that are interesting for you.

Now that the event data is setup, we have to add some ticket categories (In this sample: 100 Tickets available in a category called "Normal Entrance", each costs 100,00 EUR).
See Ticket categories Create

 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/ticketCategory/create?apikey=<yourApiKey>&version=1&format=json&name=Normal%20Entrance&price=10000&available=100
 Result:
 {"success":true}

Again, this call provides many more parameters, look them up in the documentation and add the ones that are interesting for you.

Now your event is fully setup. You can access it in your account and do test purchases if you want. If you want to start selling real tickets, the last step you have to do is activate your event.
See Event Activate

 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/activate?apikey=<yourApiKey>&version=1&format=json
 Result:
 {"success":true}

Your event is live now and starts selling tickets.
The URL to your event can be easily retrieved by reading the details of your event by API.
See Event Read

 GET: 
 https://www.xing-events.com/api/event/<yourEventId>?apikey=<yourApiKey>&version=1&format=json
 Result:
 {
 "event":{"visibility":"public","hostId":345948901, "eventURL":<yourEventUrl>...
 }, "success":true}

The value in <yourEventUrl> is the link to your event. You can publish this URL or use it to include an IFrame of the shop in your page.
Happy selling...

In case the activate call throws an errors, your account is probably not fully setup already. For example if in your account no bank account has been entered yet, the event can not be activated. This can also be done by API, but best way to assure this is to create your first event manually in our web interface.


Pre-fill the ticketshop with buyer data via REST API

One more complex example is to pre-fill the ticketshop IFrame with information you already have about the potential buyer. If for example you have a logged-in platform on your own and a database containing the address and/or other additional data about your ticket buyers, you may want to show the user a ticketshop that is already pre-filled with his accounts data without the need to re-enter everything again in the registration form.

At first you need to get the some internal ids. These are one-time calls you can also do manually once the event is set up, the ids will never change.

You get the event ID by passing in the event identifier (for example you can see the identifier of the event in the event-URL: www.xing-events.com/<yourEventIdentifier>.html):
See Event Find

 GET: 
 https://www.xing-events.com/api/event/find?identifier=<yourEventIdentifier>&apikey=<yourApiKey>&version=1&format=json
 Result: 
 {"ids":[<yourEventId>],"success":true}

Now we have the event ID and need to get the IDs of the categories of the event:
See Enumerate ticket categories

 GET:
 https://www.xing-events.com/api/event/<yourEventId>/ticketCategories?apikey=<yourApiKey>&version=1&format=json
 Result:
 {"success":true,"ticketCategories":[<yourCategoryId1>, <yourCategoryId2>]}

Let's assume you only have one ticket category in your event, this call will return only one ID for that category (<yourCategoryId>).

If you request additional data besides the standard fields (first name, last name, email, ...), we will also need the IDs of that additional user data fields to prefill them later.
See Enumerate userDataFields

 GET:
 https://www.xing-events.com/api/event/<yourEventId>/userData?apikey=<yourApiKey>&version=1&format=json
 Result:
 {"userData":[{"title":"Industry","required":false,"fieldId":<yourUserDataId1>,"type":"string"},
 {"title":"Position in company","required":false,"fieldId":<yourUserDataId2>,"type":"string"}],
 "success":true}

In this example you additionally want to know in what industry the buyer is working in and what position he has in his company.


Now to the calls that need to happen on the page where you want to show the integrated ticketshop to the logged-in user on your website. If the user clicks on a button like "buy tickets", you would open a page that does the following API calls and afterwards shows the pre-filled ticketshop in an IFrame to the user.

We start by creating a new payment and getting the ID of the created object:
See Payment Create

 POST:
 https://www.xing-events.com/api/event/<yourEventId>/payment/create?apikey=<yourApiKey>&version=1&format=json
 Result:
 {"id": <yourPaymentId>,"success":true}

Now we need to add a ticket to the new payment (using the new payment ID and the ticket category ID):
See Payment Set ticket count

 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/setTicketCount?apikey=<yourApiKey>&version=1&format=json&<yourCategoryId>=1
 Result:
 {"success":true}

Now we can start pre-filling the data for the user with the information you have in your database

Add billing address to the payment:
See Address update

 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/address/buyer?apikey=<yourApiKey>&version=1&format=json&firstName=John&lastName=Doe&email=john.doe@example.com&street=Example%20street%2033&city=Capital%20City&zipCode=12345&country=DE
 Result:
 {"success":true}

You can also store additional data in the fields you request for every ticket. To do that, we need to get the ID(s) of the tickets we created first:
See Enumerate tickets

 GET:
 https://www.xing-events.com/api/payment/<yourPaymentId>/tickets?apikey=<yourApiKey>&version=1&format=json
 Result:
 {"success":true,"tickets":[<yourTicketId>]}

Now we can set some data for one or each ticket (in this case I set the Industry to "Internet" and the user's position in his company to "Sales Manager")
See Set UserDataFields

 POST:
 https://www.xing-events.com/api/ticket/<yourTicketId>/userData?apikey=<yourApiKey>&version=1&format=json&<yourUserDataId1>=Internet&<yourUserDataId2>=Sales%20Manager
 Result:
 {"success":true}

Now everything is prepared, so we call the payment’s start function to get the URL for the prefilled IFrame that we integrate into our page and show to the user.

Start the payment process:
See Start payment

 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/start?apikey=<yourApiKey>&version=1&format=json
 Result:
 {"startIdentifier":"<startIdentifier>",
 "startUrl":"https://www.xing-events.com/<yourEventIdentifier>.html?startIdentifier=<startIdentifier>
 &queueIdentifier=<queueIdentifier>&viewType=iframe", "queueIdentifier":"<queueIdentifier>",
 "success":true}

We could now simply use the returned URL to display the IFrame:

 <iframe src="https://www.xing-events.com/<yourEventIdentifier>.html?startIdentifier=<startIdentifier>
 &queueIdentifier=<queueIdentifier>&viewType=iframe"></iframe>

Let's do this a little bit nicer. The above IFrame would not be able to get our nice automatic height adaption and the user would have to scroll on every step. To get the automatic height adaption of the IFrame you should additionally add the parameter "&resizeIFrame=true" the URL, before the <iframe>-Tag add our resize JavaScript and provide the name and id "_amiandoIFrame" to the tag.
Full Example:

 <script type="text/javascript" src="https://www.xing-events.com/resources/js/amiandoExport.js"></script>
 <iframe src="https://www.xing-events.com/<yourEventIdentifier>.html?startIdentifier=<startIdentifier>
 &queueIdentifier=<queueIdentifier>&viewType=iframe&resizeIFrame=true" frameborder="0" width="650px"
 height="450px" name="_amiandoIFrame" id="_amiandoIFrame">
 <p>This page requires frame support. 
 Please use a frame compatible browser to see the XING EVENTS ticket sales widget.
 </p></iframe>

The above IFrame will show the first step (where the user selects his tickets), but as we already selected a ticket for him, it can make sense to skip that step. If you do not do this and want the user to be able to select any ticket himself, be prepared, that any information you pre-filled on the ticket level will be lost. To do this simply add "&step=buyerData" to the URL.
Full Example:

 <script type="text/javascript" src="https://www.xing-events.com/resources/js/amiandoExport.js"></script>
 <iframe src="https://www.xing-events.com/<yourEventIdentifier>.html?startIdentifier=<startIdentifier>
 &queueIdentifier=<queueIdentifier>&viewType=iframe&resizeIFrame=true&step=buyerData" frameborder="0"
 width="650px" height="450px" name="_amiandoIFrame" id="_amiandoIFrame">
 <p>This page requires frame support. 
 Please use a frame compatible browser to see the XING EVENTS ticket sales widget.
 </p></iframe>

You can even "jump" to any later step of the shop, but be prepared to see errors in case you skip a step for which you did not provide all mandatory data by API.
Possible values for the step parameter are:

buyerData Step where the user provides his billing address
ticketData Step where the user provides his ticket data
paymentOptions Step where the user can choose between E-Ticket and paper ticket, etc.
paymentData Step where the user provides his billing information, e.g. credit card data
checkData Last step in the shop where the user validates his purchase (as you can't pre-fill payment information by API, this step should never be used if the payment is not free!)

Create a complete registration with API only

In case you have alternative registration processes (e.g. by phone/fax or your own online registration form), you can also create tickets in our system via API. Another use case is to import already known attendees (e.g. staff or VIPs) into our system.
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.

  1. To create a new attendee/ticket in your event we recommend to use the Participants Create call.

  1. Alternatively you can go through the process of creating the payment, ticket, etc. succesuccessively.
    To create and finalize a payment, please follow the steps in the example above Pre-fill the ticketshop IFrame with buyer data.
    The last step of the above sample is the Start payment call. After that call, instead of showing the ticketshop IFrame to the user, you can do an additional API call to finalize the payment.
    see Finalize payment
 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/finalize?apikey=<yourApiKey>&version=1&format=json&queueIdentifier=<queueIdentifier>&acceptedTermsAndConditions=1
 Result:
 {"success":true}

PHP example

Here is a small PHP script which will create an event and within this event a new attendee via our REST API. The source code can be downloaded as zip file here: api.zip

Pre-fill the ticketshop with buyer data via URL parameters

See our How-To on this page: Pre-fill data in ticket shop

Conversion tracking

Using our (Browser-)Webhook it is possible to integrate any kind of conversion tracking. A typical use case is: You are placing advertisments for your event on Google AdWords, Facebook, etc. and want to track how that ad performs. So not only how many people clicked the advertisement, but also how many really bought a ticket.
See our Conversion tracking sample for how to set this up with Facebook Ads (all other systems work very similar).

Integrate and automate with Zapier

See our How-To on this page: Zapier