Overview

The purpose of this document is to describe the APIs needed in order to implement the integration between Ticketsetup Web Portal and Ticketsetup Server systems and fulfill the customer needs. These API are REST web services that can be used by any of the Interface (Platform such as iPhone, Android etc) in future if required.

Note: All API requests should hit the secured endpoint i.e. only HTTPS

Changelog

July 2013

  • Updated XML response of Get Event Details. Added 2 new parameters tpSold and tpLeft for the total number of tickets sold and left respectively.
  • Updated XML response. ticketSuccessStaus removed, and valid is considered for success case return. Added 2 new parameters ticketReservationType (1-reserved, 2-ordered, 3-refunded) and ticketExpired (1-expired, 0-expired).
  • Updated XML response of Get Event Details. Added new parameters entryStartTime, entryEndTime, daysActive. ticketPriceList is now coming user schedData
  • Updated Create and Edit Event API functions to save additional parameters - entryStartTime, entryEndTime, daysActive.
  • Updated Check Ticket. Return value approach has changed. If ticket exists, always ticket information is returned.
  • Updated Reserve Ticket. Added additional parameter email and desiredDate.
  • Updated Remove Event Schedule API function to send removal notification text via email to ticket owners (in case of any ticket sold)

June 2013

  • Updated XML request for Check and Control API to send Ticket Id in form of String and XML response to return ticket number, event id and schedule id in return.
  • Updated XML response for the Suspend Event Schedule for the case when few tickets were sold for that event.
  • Added new API functions - Control Ticket, Get Ticket History

May 2013

  • Added new API functions - Refund Tickets, Check Tickets
  • Added new API functions - Release Tickets, Order Tickets
  • Added new API functions - Reserve Tickets

April 2013

  • ETMS API Document for Event organizer and Distributer Register ration, Login, update Profile, Event Management
Ticketsetup

User Type

Text must be here.

Source Value
Organiser 1
Distributor 2
Controller 3

Register an User

This web service allows an event organizer to register within the ETMS Application.

postpublic
/api/user/register.xml [.json]

Parameters

Attribute Type Description
firstName string The user’s first name
lastName string The user’s last name
company string The user's company
phone string The user's contact phone number
streetAddress string The user's street address
postaCode string The user's country code
city string The user's street address
email string The user's email. This mail will be use for login name.
password string The user's password. This password will be encode to SHA1 format.
userType (mandatory) integer The user's type. By default value is 1.
userId (optional) string The user's extra ID. By default value is etms.

Request

<user>
  <firstName>API</firstName>
  <lastName>Developer</lastName>
  <company>Ticketsetup Inc.</company>
  <phone>(+1) 23 456-78-90</phone>
  <streetAddress>Some Address</streetAddress>
  <postalCode>AZ</postalCode>
  <city>Baku</city>
  <country>Azerbaijan</country>
  <email>api@ticketsetup.com</email>
  <password>qwerty</password>
  <userType>1</userType>
  <extraId>etms</extraId>
</user>
{
	"firstName": "API",
	"lastName": "Developer",
	"company": "Ticketsetup Inc.",
	"phone": "(+1) 23 456-78-90",
	"streetAddress": "Some Adress",
	"postalCode": "AZ",
	"city": "Baku",
	"country": "Azerbaijan",
	"email": "api@ticketsetup.com",
	"password": "qwerty",
	"userType": "1"
}

Response

<responseMessage>
    <code>200</code>
    <message>User Registered Successfully</message>
    <object xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="user">
        <availSince>0000-00-00T00:00:00+04:00</availSince>
        <availTill>0000-00-00T00:00:00+04:00</availTill>
        <city>Baku</city>
        <company>Ticketsetup Inc.</company>
        <country>Azerbaijan</country>
        <email>api@ticketsetup.com</email>
        <extraId>etms</extraId>
        <firstName>API</firstName>
        <lastName>Developer</lastName>
        <password>B1B3773A05C0ED0176787A4F1574FF0075F7521E</password>
        <phone>(+1) 23 456-78-90</phone>
        <postalCode>AZ</postalCode>
        <streetAddress>Some Address</streetAddress>
        <userId>11</userId>
        <userType>1</userType>
        <verified>0</verified>
        <verifyCode>l03dccjjr9f7i</verifyCode>
    </object>
    <serverVersion>1.87.736</serverVersion>
    <status>OK</status>
</responseMessage>
{
  "responseMessage": {
    "code": 200,
    "status": "OK",
    "message": "User Registered Successfully",
    "object": {
      "userId": 11,
      "eventId": null,
      "availSince": 1492963006131,
      "availTill": 1492963006131,
      "verified": 0,
      "verifyCode": "rep24fk8e58ev",
      "city": "Baku",
      "company": "Ticketsetup Inc.",
      "country": "Azerbaijan",
      "email": "api@ticketsetup.com",
      "extraId": "etms",
      "firstName": "API",
      "lastName": "Developer",
      "password": "B1B3773A05C0ED0176787A4F1574FF0075F7521E",
      "phone": "(+1) 23 456-78-90",
      "postalCode": "AZ",
      "streetAddress": "Some Adress",
      "userType": "ORGANIZER",
      "allowIp": null,
      "restrictIp": null,
      "sessionDuration": null,
      "events": null,
      "reservations": null,
      "resetPasswords": null,
      "sessions": null,
      "sharedEvents": null,
      "session": null,
      "vCode": null,
      "eventListFilter": null,
      "eventAccessList": null,
      "fullName": "API Developer"
    },
    "list": null,
    "serverVersion": "1.87.736t"
  }
}

Errors

Code Status Message
409 ALREADY EXIST User name is already exist.
500 INTERNAL SERVER ERROR Unable to register the user.

User Login

This web service allows a user (organizer or distributor) to login within account's credentials.

postpublic
/api/user/login.xml [.json]

Parameters

Attribute Type Description
email string The user’s email as login
password string The user’s password must be encode in SHA1.
extraId (optional) string The user's extra id. By default value is etms.

Request

<user>
  <email>api@ticketsetup.com</email>
  <password>B1B3773A05C0ED0176787A4F1574FF0075F7521E</password>
</user>
{
	"email": "api@ticketsetup.com",
	"passord": "B1B3773A05C0ED0176787A4F1574FF0075F7521E"
}

Response

<responseMessage>
    <code>200</code>
    <message>Login Success</message>
    <object xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="UserDetails">
        <userId>3</userId>
        <city>Baku</city>
        <company></company>
        <country>AZ</country>
        <email>api@ticketsetup.com</email>
        <extraId>etms</extraId>
        <firstName>ETMS</firstName>
        <lastName>Distributor</lastName>
        <phone></phone>
        <postalCode></postalCode>
        <streetAddress></streetAddress>
        <userType>2</userType>
        <session>d5fsfpmtacn1f</session>
    </object>
    <serverVersion>1.87.736</serverVersion>
    <status>OK</status>
</responseMessage>
{
	"responseMessage": {
    	"code": 200,
		"status": "OK",
		"message": "Login Success",
		"object": {
			"userId": 3,
			"city": "Baku",
			"company": "",
			"country": "AZ",
			"email": "api@ticketsetup.com",
			"extraId": "etms",
			"firstName": "ETMS",
			"lastName": "Distributor",
			"phone": "",
			"postalCode": "",
			"streetAddress": "",
			"userType": 2,
			"session": "javvcog8a3vp3",
			"fullName": "ETMS Distributor"
		},
		"list": null,
		"serverVersion": "1.87.736"
	}
}

Errors

Code Status Message
401 UNAUTHORIZED The username or password is incorrect.
401 UNVERIFIED This user account is not verified yet.

Change Password

This web service allows a user (event organizer, distributor) to change the password of his/her ETMS account.

Note: The web service first authenticates the user session with user id. If its valid then it updates the new password change requested by user.

postpublic
/api/user/change/password.xml [.json]

Request

<user>
  <email>api@ticketsetup.com</email>
  <password>B1B3773A05C0ED0176787A4F1574FF0075F7521E</password>
</user>
{
	"email": "api@ticketsetup.com",
	"passord": "B1B3773A05C0ED0176787A4F1574FF0075F7521E"
}

Response

<responseMessage>
    <code>200</code>
    <message>Login Success</message>
    <object xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="UserDetails">
        <userId>3</userId>
        <city>Baku</city>
        <company></company>
        <country>AZ</country>
        <email>api@ticketsetup.com</email>
        <extraId>etms</extraId>
        <firstName>ETMS</firstName>
        <lastName>Distributor</lastName>
        <phone></phone>
        <postalCode></postalCode>
        <streetAddress></streetAddress>
        <userType>2</userType>
        <session>d5fsfpmtacn1f</session>
    </object>
    <serverVersion>1.87.736</serverVersion>
    <status>OK</status>
</responseMessage>
{
	"responseMessage": {
    	"code": 200,
		"status": "OK",
		"message": "Login Success",
		"object": {
			"userId": 3,
			"city": "Baku",
			"company": "",
			"country": "AZ",
			"email": "api@ticketsetup.com",
			"extraId": "etms",
			"firstName": "ETMS",
			"lastName": "Distributor",
			"phone": "",
			"postalCode": "",
			"streetAddress": "",
			"userType": 2,
			"session": "javvcog8a3vp3",
			"fullName": "ETMS Distributor"
		},
		"list": null,
		"serverVersion": "1.87.736"
	}
}

Errors

Code Status Message
401 UNAUTHORIZED The username or password is incorrect.
401 UNVERIFIED This user account is not verified yet.

Events Properties

Every ticket uses certain fixed numerical values to denote its Status, and Priorities. These numerical values along with their meanings are given below.

Ticketsetup
Source Value
Seat Based 1
Event Based 2
Status Value
Open 2
Pending 3
Resolved 4
Closed 5

Create an Event

This web service crates a new event within ETMS DB.

post public
/api/event/create.xml [.json]

Parameters

Attribute Type Description
pdfTemplate number Ticket PDF template. The Default value is 0.
maximumLimit number The Default value is 4.
ticketType * string Values are “SEAT” or “EVENT”
propertyList number
maxInvitations number Values: -1 (unlimited), >= 0 (limited). Default value is 0.

Response

<event>
	<user>
		<userId>number</userId>
	</user>
	<session>string</session>
	<eventName>string</eventName>
	<eventDesc>string</eventDesc>
	<venue>
		<venueId>number</venueId>
	</venue>
	<pdfTemplate>
		<ptId>number</ptId>
	</pdfTemplate>
	<genre>
		<genreId>number</genreId>
	</genre>
	<timeZone>GMT+4</timeZone>
	<promotion>string</promotion>
	<invitationTitle>Invitation</invitationTitle>
	<propertyList>
		<property>
			<propertyId>number</propertyId>
			<propertyDesc>string</propertyDesc>
		</property>
	</propertyList>
	<imagePortraitFile>/absolute/path/to/image</imagePortraitFile>
	<imageLandscapeFile>/absolute/path/to/image</imageLandscapeFile>
	<scheduleList>
		<schedule>
			<schedDateTime>0000-00-00 00:00:00</schedDateTime>
			<entryStartTime>00:00:00</entryStartTime>
			<entryEndTime>00:00:00</entryEndTime>
			<schedExtraTime>true / false</schedExtraTime>
			<daysActive>nubmer</daysActive>
			<maxInvitations>number</maxInvitations>
		</schedule>
	</scheduleList>
	<ticketPricesList>
		<ticketPrice>
			<tpName>string</tpName>
			<tpPrice>number</tpPrice>
			<tpQuantity>number</tpQuantity>
			<tpDesc>string</tpDesc>
			<currency>
				<currId>number</currId>
			</currency>
			<maximumLimit>10</maximumLimit>
			<minimumLimit>2</minimumLimit>
			<salesStartDate>0000-00-00T00:00:00+04:00</salesStartDate>
			<salesEndDate>0000-00-00T00:00:00+04:00</salesEndDate>
			<ticketType>SEAT / BASE</ticketType>
		</ticketPrice>
	</ticketPricesList>
</event>
{
	"event": {
		"user": {
			"userId": "number"
		},
		"session": "string",
		"eventName": "string",
		"eventDesc": "string",
		"venue": {
			"venueId": "number"
		},
		"pdfTemplate": {
			"ptId": "number"
		},
		"genre": {
			"genreId": "number"
		},
		"timeZone": "GMT+4",
		"promotion": "string",
		"invitationTitle": "Invitation",
		"propertyList": {
			"property": [
				{
					"propertyId": "number",
					"propertyDesc": "string"
				}
			]
		},
		"imagePortraitFile": "/absolute/path/to/image",
		"imageLandscapeFile": "/absolute/path/to/image",
		"scheduleList": {
			"schedule": [
				{
					"schedDateTime": "0000-00-00 00:00:00",
					"entryStartTime": "00:00:00",
					"entryEndTime": "00:00:00",
					"schedExtraTime": "true / false",
					"daysActive": "number",
					"maxInvitations": "number"
				}
			]
		},
		"ticketPricesList": {
			"ticketPrice": [
				{
					"tpName": "string",
					"tpPrice": "number",
					"tpQuantity": "number",
					"tpDesc": "string",
					"currency": {
						"currId": "number"
					},
					"maximumLimit": "number",
					"minimumLimit": "number",
					"salesStartDate": "0000-00-00T00:00:00+04:00",
					"salesEndDate": "0000-00-00T00:00:00+04:00",
					"ticketType": "SEAT / BASE"
				}
			]
		}
	}
}