CrowdSeats Checkout API

README.md

Version

The current API Version is 1. The Version number will always be incremented in whole integers. You can access specific versions of the API by providing that version number in your API calls, which are detailed further below.

Entry Point

The current version of the CrowdSeats Checkout API is available at: http://api-checkout.crowdseats.com/1.

Authentication

The CrowdSeats Checkout API requires an API key to access which is provided when you sign up for API access. The API key identifies your application to CrowdSeats, and is used to track overall call usage. It's passed using the api_key parameter that you will need to supply on every API call. In addition to your API key, you will also need to include an authentication token using the auth_token parameter.

API Requests

The CrowdSeats Checkout API uses a RESTful calling style that works with standard HTTP calls. In other words, all calls are just HTTP URLs. Any web programming language (PHP, Ruby, Perl, Python, Java, Objective C, C# to name a few) should be able to make and receive HTTP networking calls, so check out the documentation for your language of choice for more details.

In a RESTful API, each resource or collection of resources is identified by a unique URL, such as:

http://api-checkout.crowdseats.com/1/Checkout/:listing_id

It's a bit more complicated than that, however, since every request you make needs to have your API key supplied. Think of this as your user id and password. Since RESTful web services are generally stateless, you need to supply those credentials in every request.

In addition, you must specify which version of the API you'd like to call. As mentioned earlier, this is a simple integer value that gets incremented every time significant changes to the API are made (changes that would break compatibility with existing applications). If you can't keep up with CrowdSeats' Checkout API changes and don't want to use the latest and greatest version, then you can always supply an earlier version specifier in your call. We'll do our best to keep the older versions of the API hanging around.

So the basic format for any URL to call the CrowdSeats Checkout API is as follows:

http://api-checkout.crowdseats.com/{apiVersion}/{pathToResource}?api_key={:api_key}

A full example of an API call would be the following:

http://api-checkout.crowdseats.com/1/Checkout/00000000-0000-0000-0000-000000000000?api_key=0FFA1519-22D6-454E-B2FA-9D9F017D522E

URLs for specific API calls are discussed in more detail in the sections that follow.

The default format for the service is JSON, in order to access the service, make sure the Content-Type (set in the request header) of the request is set to:

Content-Type: application/json; charset=utf-8

HTTP Methods

RESTful APIs use standard HTTP methods for actions that can be applied to a resource:

Method	Description	Status Code
GET	Reads a resource	HTTP 200 on success
POST	Creates a new resource	HTTP 201 on success
PUT	Inserts or Updates a resource	HTTP 200 on success
DELETE	Deletes a resource	HTTP 200 on success

API Responses

All GET API calls will return a JSON response within a standard data structure that also contains additional meta-data:

{
     "count":integer,
     "results": [
         { result object }
     ],
     "type":result type
}

Where count is the number of results returned, results is the array of the returned objects, and type is the type of the object returned.

For the sake of consistency, the result field will always return an array, even if the number of results returned is 1.

For POST, PUT and DELETE API calls, a status JSON response message will be returned:

{
     "type": "Result",
     "results": [{ message: "Event deleted", data: [null] }],
     "count": 1
}

Response Codes

As with all RESTful interfaces, the CrowdSeats Checkout API uses standard HTTP status codes to indicate success or failure of API calls. Determining the HTTP status code of the returned response is dependent on your toolkit/programming language so consult its documentation for implementation details.

HTTP Code	Message	Meaning
200	OK	Success
201	Created	A new resource was successfully created.
400	Bad Request	Your request contains an error, such as passing a string for a parameter that expects an integer.
401	Unauthorized	Your request contained an incorrect api_key and/or other authentication parameters.
403	Forbidden	The rate limits for your account have been exceeded, the data you're trying to access is private, or the method you're using is not allowed for that particular resource.
404	Not Found	The requested resource could not be found or does not correspond to any known operation.
500	Server Error	An unexpected error has occurred on our end.
503	Service Unavailable	The CrowdSeats Checkout API is down for scheduled maintenance; please try again later (this should hardly ever happen though!)

All responses return a JSON-formatted result body, even for errors. For status codes other than 200 and 201, an error object is returned in the response body, with exact details on the cause of the error. For example:

{
    "http_status_code":401,
    "errors": { message: [ "invalid_city_code", "invalid_date_range" ] }
}

What's the difference between a 404 Not Found and a 200 OK with empty results? If you're searching for a specific record, say event BA5965A4-EAF4-44CC-B3A8-011ED7220E73, and it doesn't exist, 404 Not Found is returned. The record wasn't found in our system because it no longer exists (or maybe never even existed). However, if you're searching for a set of events and no listings match your search, 200 OK is returned, but with an empty array in the results field. There's nothing wrong with your request, but there were no matching records found so an empty result is returned.

While this may seem a bit weird, it makes practical sense: if you use a search engine to find something and no matching results were found, it doesn't return an error page. But if you're trying to access a URL that doesn't exist, a standard 404 error page would be returned. It's likely that your application should behave similarly.

Error Codes

If an error response is returned, the message field will contains an array of error codes. Each error code meant to be human-readable but can be treated as a constant and used in your application to respond to the error accordingly. We will explain each call-specific error code later but here are the system wide error codes:

Error Code	Meaning
invalid_api_key	The API key used is invalid.

Checkout.md

CrowdSeats Checkout API

POST /Checkout/:ticket_id

Purchases a ticket identified by ticket_id

Parameter	Value	Type	Location	Description
ticket_id	required	string	query or header	Your unique ID for this ticket.
api_key	required	string	query or header	API key
auth_token	required	string	query or header	Authentication token that pairs to the api_key

Entity Body

Parameter	Value	Type	Description
AffiliateCode	optional	string	Optional affiliate code to indicate this order originated via an affiliate
AffiliateTrackingId	optional	string	Optional tracking identifier used by an affiliate for them to track an order
Amount	required	string	Total expected amount of the order
BillingAddress	required	Address object	Address to bill this order to
CheckoutId	required	string	Identity of the ThreatMetrix client session ID for the current user
CreditCard	required	CreditCard object	Payment information for this order
DeliveryMethod	One of: ship, email	enumerated	Method of ticket delivery
Quantity	One of: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16	enumerated	Quantity of tickets in this order
ShippingAddress	conditional	Address object	Address to ship this order to, if DeliveryMethod is ship
User	required	object	User information for this order

Address object

Parameter	Value	Type	Description
Address1	required	string	Street address
Address2	optional	string	Suite, building, or care-of information
FirstName	required	string	First name of contact associated with this address
LastName	required	string	Last name of contact associated with this address
PostalCode	required	string	Postal code
State	required	string	State

CreditCard object

Parameter	Value	Type	Description
PaymentMethodToken	required	string	Spreedly payment method token generated for CrowdSeats

User object

Parameter	Value	Type	Description
Email	required	string	Email address
Password	optional	string	Optional password to associate with the user
FirstName	required	string	First name
LastName	required	string	Last name
Phone	required	string	Phone number
IpAddress	required	string	IP Address of the user. This should only represent the end-user, not any load balancers, or intermediary network devices
OptIntoScoreBigMarketingOffers	One of: true, false	enumerated	Determines whether to opt the user in to marketing offers from ScoreBig

Example request

POST /1/Checkout/00000000-0000-0000-0000-000000000000
api_key: your_api_key
auth_token: your_auth_token
Content-Type: application/json; charset=utf-8

{
  "AffiliateCode": "affiliate_code",
  "AffiliateTrackingId": "your_tracking_id",
  "Amount": "100.00",
  "BillingAddress": {
    "Address1": "1800 N. Highland Ave.",
    "Address2": "Floor 1",
    "City": "Hollywood",
    "FirstName": "John",
    "LastName": "Doe",
    "PostalCode": "90028",
    "State": "CA"
  },
  "CheckoutId": "00000000-0000-0000-0000-000000000000",
  "CreditCard": {
    "PaymentMethodToken": "spreedly_payment_method_token"
  },
  "DeliveryMethod": "ship",
  "Quantity": 2,
  "ShippingAddress": {
    "Address1": "1800 N. Highland Ave.",
    "Address2": "Floor 1",
    "City": "Hollywood",
    "FirstName": "John",
    "LastName": "Doe",
    "PostalCode": "90028",
    "State": "CA"
  },
  "User": {
    "Email": "john.doe@qa.scorebiginc.com",
    "FirstName": "John",
    "LastName": "Doe",
    "Phone": "8885551212",
    "IpAddress": "127.0.0.1",
    "OptIntoScoreBigMarketingOffers": true
  }
}

Example responses

Success:

{"Http_Status_Code":200,"type":"Result","count":1,"results":[{"OrderId": "00000000-0000-0000-0000-000000000000", "ConfirmationNumber": "123456789"}],"Errors":{}}

Invalid API key or auth token:

{"Http_Status_Code":401,"type":"Error","count":0,"results":[],"Errors":{"unauthorized":["The API key provided could not be authorized"]}}

Model validation failure:

{"Http_Status_Code":500,"type":"Error","count":0,"results":[],"Errors":{"BillingAddress":["Required"],"CreditCard":["Required"],"Quantity":["You must select a quantity."],"User":["Required"]}}

Delivery method not available:

{"Http_Status_Code":401,"type":"Error","count":0,"results":[],"Errors":{"delivery_method_not_avaliable":["The selected delivery method is not avaliable for this ticket"]}}

Order amount mismatch:

{"Http_Status_Code":401,"type":"Error","count":0,"results":[],"Errors":{"amount_mismatch":["Expected amount 11.00, got 10.00 instead"]}}