View source for How-Tos

{{TOCright}}
==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===
{|border="1" style="border-collapse:collapse"
! style="text-align:left;"|integration
! advantages
! disadvantages
|- style="vertical-align:top;"
|1.&nbsp;Export/Import
| - No complex setup<br>- No technical knowledge needed
| - Manual work each time to update the data
|- style="vertical-align:top;"
|2.&nbsp;Zapier
| - No complex setup<br>- No technical knowledge needed
| - Your CRM might not be supported by Zapier<br>- Costs for the Zapier service might apply<br>- Data is only send once after the purchase, no update of data if changes are done afterwards
|- style="vertical-align:top;"
|3.&nbsp;Webhook
| - Only small development needed
| - Data is only send once after the purchase, no update of data if changes are done afterwards <br> - Only default fields are available (see webhook documentation)
|- style="vertical-align:top;"
|4.&nbsp;REST&nbsp;API/SYNC
| - Data is always up-to-date
| - Development needed
|}

===Information===
<p>
'''1.&nbsp;Export/Import'''<br>
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.<br>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.
</p>
<p>
'''2.&nbsp;Zapier'''<br>
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|Zapier documentation]] for more details.<br>
</p>
<p>
'''3.&nbsp;Webhook'''<br>
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.<br>
Please see our [[Tracking_Webhooks|Webhook documentation]] for more details.<br>
We recommend to use the "server-call" webhook for this type of integration as those are more reliable.<br>
</p>
<p>
'''4.&nbsp;REST&nbsp;API/SYNC'''<br>
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.<br>
You need to do an initial loading of all existing participants using the "[[REST_API_Events#Enumerate_participants|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.<br/>
For more information please read our [[REST_API|REST API documentation]].<br>
The most important calls you need for this integration are probably:<br>
[[REST_API_Users#Find|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)<br>
[[REST_API_Users#Enumerate_events|Enumerate events]] to get all events of your account<br>
[[REST_API_Events#Enumerate_participants|Enumerate participants]] to get all the participants of each of your events<br>
[[REST_API_Participants|Participants object]] that shows you the data we provide for each participant<br>
[[REST_API_DataSync_v2|SYNC API]] to keep your system up to date and only load data that has changed
</p>

==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 EventManager 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).
<br/>See [[REST_API_Users#Find|User Find]]
<pre>
 GET: 
 https://www.xing-events.com/api/user/find?apikey=<yourApiKey>&username=<yourUsername>
 Result: 
 {"ids":[<yourUserId>],"success":true}
</pre>


Now you can create the event and provide different data describing the event.
<br/>See [[REST_API_Events#Create|Event Create]]
<pre>
 POST: 
 https://www.xing-events.com/api/event/create?apikey=<yourApiKey>&hostId=<yourUserId>&title=Awesome%20Event&country=DE&selectedDate=2016-01-01T08:00:00
 Result: 
 {"id":[<yourEventId>],"success":true}
</pre>
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):
<br/>See [[REST_API_Events#Logo_upload|Logo upload]]
<br/>See [[REST_API_Events#Banner_upload|Banner upload]]
<pre>
 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/banner?apikey=<yourApiKey>
 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}
</pre>
This is an example using curl:
<pre>
 curl -i "https://xing-events.com/api/event/<yourEventId>/banner?apikey=<yourApiKey>" -H "Content-Type: image/jpeg" --data-binary @path/to/file.jpg
</pre>

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).
<br/>See [[REST_API_TicketShops#Update|TicketShop Update]]
<pre>
 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/ticketShop?apikey=<yourApiKey>&salesTax=1900&currency=EUR
 Result:
 {"success":true}
</pre>
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).
<br/>See [[REST_API_TicketCategories#Create|Ticket categories Create]]
<pre>
 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/ticketCategory/create?apikey=<yourApiKey>&name=Normal%20Entrance&price=10000&available=100
 Result:
 {"success":true}
</pre>
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.
<br/>See [[REST_API_Events#Activate|Event Activate]]
<pre>
 POST: 
 https://www.xing-events.com/api/event/<yourEventId>/activate?apikey=<yourApiKey>
 Result:
 {"success":true}
</pre>

Your event is live now and starts selling tickets. <br/>
The URL to your event can be easily retrieved by reading the details of your event by API.
<br/>See [[REST_API_Events#Read|Event Read]]
<pre>
 GET: 
 https://www.xing-events.com/api/event/<yourEventId>?apikey=<yourApiKey>
 Result:
 {
 "event":{"visibility":"public","hostId":345948901, "eventURL":<yourEventUrl>...
 }, "success":true}
</pre>
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.<br/>
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):
<br/>See [[REST_API_Events#Find|Event Find]]
<pre>
 GET: 
 https://www.xing-events.com/api/event/find?identifier=<yourEventIdentifier>&apikey=<yourApiKey>
 Result: 
 {"ids":[<yourEventId>],"success":true}
</pre>

Now we have the event ID and need to get the IDs of the categories of the event:
<br/>See [[REST_API_Events#Enumerate_ticket_categories|Enumerate ticket categories]]
<pre>
 GET:
 https://www.xing-events.com/api/event/<yourEventId>/ticketCategories?apikey=<yourApiKey>
 Result:
 {"success":true,"ticketCategories":[<yourCategoryId1>, <yourCategoryId2>]}
</pre>
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.
<br/>See [[REST_API_Events#Enumerate_userDataFields|Enumerate userDataFields]]
<pre>
 GET:
 https://www.xing-events.com/api/event/<yourEventId>/userData?apikey=<yourApiKey>
 Result:
 {"userData":[{"title":"Industry","required":false,"fieldId":<yourUserDataId1>,"type":"string"},
 {"title":"Position in company","required":false,"fieldId":<yourUserDataId2>,"type":"string"}],
 "success":true}
</pre>

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:
<br/>See [[REST_API_Payments#Create|Payment Create]]
<pre>
 POST:
 https://www.xing-events.com/api/event/<yourEventId>/payment/create?apikey=<yourApiKey>
 Result:
 {"id": <yourPaymentId>,"success":true}
</pre>

Now we need to add a ticket to the new payment (using the new payment ID and the ticket category ID):
<br/>See [[REST_API_Payments#Set_ticket_count|Payment Set ticket count]]
<pre>
 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/setTicketCount?apikey=<yourApiKey>&<yourCategoryId>=1
 Result:
 {"success":true}
</pre>

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:
<br/>See [[REST_API_Addresses#Update|Address update]]
<pre>
 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/address/buyer?apikey=<yourApiKey>&firstName=John&lastName=Doe&email=john.doe@example.com&street=Example%20street%2033&city=Capital%20City&zipCode=12345&country=DE
 Result:
 {"success":true}
</pre>

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:
<br/>See [[REST_API_Payments#Enumerate_tickets|Enumerate tickets]]
<pre>
 GET:
 https://www.xing-events.com/api/payment/<yourPaymentId>/tickets?apikey=<yourApiKey>
 Result:
 {"success":true,"tickets":[<yourTicketId>]}
</pre>

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")
<br/>See [[REST_API_Tickets#Set_UserDataFields|Set UserDataFields]]
<pre>
 POST:
 https://www.xing-events.com/api/ticket/<yourTicketId>/userData?apikey=<yourApiKey>&<yourUserDataId1>=Internet&<yourUserDataId2>=Sales%20Manager
 Result:
 {"success":true}
</pre>

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:
<br/>See [[REST_API_Payments#Start_payment|Start payment]]
<pre>
 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/start?apikey=<yourApiKey>
 Result:
 {"startIdentifier":"<startIdentifier>",
 "startUrl":"https://www.xing-events.com/<yourEventIdentifier>.html?startIdentifier=<startIdentifier>
 &queueIdentifier=<queueIdentifier>&viewType=iframe", "queueIdentifier":"<queueIdentifier>",
 "success":true}
</pre>
                
We could now simply use the returned URL to display the IFrame:
<pre>
 <iframe src="https://www.xing-events.com/<yourEventIdentifier>.html?startIdentifier=<startIdentifier>
 &queueIdentifier=<queueIdentifier>&viewType=iframe"></iframe>
</pre>

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.<br/>
Full Example:
<pre>
 <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>
</pre>

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.<br/>
Full Example:
<pre>
 <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>
</pre>

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.'''<br/>
Possible values for the step parameter are:
{| border="1" style="border-collapse:collapse;"
| 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.<br/>
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.
<br/><br/>

# To create a new attendee/ticket in your event we recommend to use the [[REST_API_Participants#Create|Participants Create]] call.<br/><br/>

# Alternatively you can go through the process of creating the payment, ticket, etc. successively.<br/>To create and finalize a payment, please follow the steps in the example above [[REST_API_Events#Pre-fill_the_ticketshop_IFrame_with_buyer_data|Pre-fill the ticketshop IFrame with buyer data]].<br/>The last step of the above sample is the [[REST_API_Payments#Start_payment|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.<br/>see [[REST_API_Payments#Finalize_payment|Finalize payment]]
<pre>
 POST:
 https://www.xing-events.com/api/payment/<yourPaymentId>/finalize?apikey=<yourApiKey>&queueIdentifier=<queueIdentifier>&acceptedTermsAndConditions=1
 Result:
 {"success":true}
</pre>

==Pre-fill the ticketshop with buyer data via URL parameters==
See our How-To on this page: [[Pre-fill_data_in_ticket_shop|Pre-fill data in ticket shop]]

==Affiliate, Campaign or similar tracking of your sales==
<p>
While [[Google Analytics]] works best if you want to have a general picture of your audience (How many attendees found you by search engines or other sources? Demographics or technology questions like how many attendees book tickets on their mobile device, etc.), another tracking case might be that you have partners (affiliates) you offer a commission for every purchased ticket coming from a link they placed on their pages. A similar case is that you execute different campaigns for which you want to measure the success (e.g. various newsletter campaigns).</p>
For the latter cases, Google Analytics might not be precise enough (or you reject it for other reasons), we then suggest tracking these with the parameter approach:<br/>
 - Our offered [[Payment_Application_Data|applicationData]] parameter can be used for these scenarios.
 - Provide every partner/campaign with a personalized link to your event page, e.g.:
     <nowiki>https://www.xing-events.com/ABCDEF.html?applicationData=Affiliate1</nowiki>, 
     <nowiki>https://www.xing-events.com/ABCDEF.html?applicationData=Affiliate2</nowiki>,...
 - If you are using your own event page and include the ticketshop as IFrame, 
     forward the parameter from your page to the ticketshop. 
 - In PHP this might look something like this:
     <nowiki>src="....html?viewType=iframe&applicationData=<?=$_GET['source']?>&..."</nowiki>
     and you can use links like this for your partners/campaigns:
     <nowiki>www.yourEventPage.com/tickets.html?source=campaign1</nowiki>,...
 - Regularly, or after the event, you can download a report in the event's backend:
     Create a custom report, add payment amount and applicationData to your report 
     and maybe filter out cancelled or unpaid tickets
 - Using the Excel file you can sort by "applicationData" and do your commission calculations 
     based on the payment's amount to pay out your affiliates.

<strong>Additional notes:</strong><br/>
<p>
Linking to the event page on xing.com is currently not supported.
</p>

== 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.<br/>
See our [[Tracking_Webhooks#Conversion_tracking_sample|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]]