The ticketing tool "amiando" is now the "XING TicketingManager". With that re-branding we switched our domain from amiando.com to xing-events.com. Please update you API implementations to use the new domain. The API will be served on amiando.com until 01.05.2017

How-Tos

From XING Events Developer Documentation
Jump to: navigation, search

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.amiando.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!)

Pre-fill the ticketshop with buyer data via URL parameters

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

Create a complete registration with API only

If a registration for an event is for free, you can even create tickets completely with the API. You can use that to build your own registration form or to import attendees into your event. 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}

After that call a new attendee will be create in your event and the system will send out the ticket by mail to that new attendee.

PHP example

At https://documents.xing-events.com/apisample/ you can find 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: https://documents.xing-events.com/apisample/api.zip

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