# TickeTing REST API v3 Reference

# Introduction
The TickeTing REST API v3 allows developers to integrate with the TickeTing 
platform, from creating hosts and events to buying and transferring tickets.
This reference document will walk you through authenticating against the API
and the full list of available endpoints, their permissions and functionality.

# Authentication
The TickeTing API uses API keys to authenticate requests. You must provide a 
valid API Key in the X-API-Key header of each request you make. There are two
ways to get a valid API Key:

1. Start a session with a valid TickeTing username and password (this gives
access based on the user's permissions).

2. Secure an integration key from a system administrator. Integration keys grant an
access level determined by the administrator on creation.

Session Authentication and Integration Keys are covered in the
[Authentication](#tag/Session-Management "Authentication") section of this reference.

### Example Request Header

~~~
X-API-Key: a9427bf35dd3d3011a1277c9c344ae07
~~~

### Authentication Errors

Omitting the X-API-Key Header from your request or specifying an empty value, will result in
the following 401 error response.

~~~
{
  "message": "Your request could not be authenticated."
}
~~~

If an invalid X-API-Key value is provided, or the provided key is valid, but does not have
permission to access the requested resource, the following 403 error response is sent.

~~~
{
  "message": "You are restricted from accessing this resource."
}
~~~

# Client Version
All requests to the API must include the version of the API they wish to integrate with.
This ensures compatability with the server. This is done by including the X-Client-Version
header in every request along with the expected API version. In this way the server can
indicate when a client must upgrade to avoid breaking changes.

### Example Request Header

~~~
X-Client-Version: 3.0.0
~~~

### Client Version Errors

If the X-Client-Version header is omitted from your request, or the provided version does
not meet the minimum required by the API, the following 412 error response
is sent.

~~~
{
    "error": "Please upgrade your client to complete this request"
}
~~~

# Error Responses

### 404 Errors

Requests to the API can result in a 404 error for two reasons:

1.  The endpoint you are trying to access does not exist, in which case you will see the
    following response:
  
    ~~~
    {
        "message": "The requested endpoint /invalid/endpoint does not exist on this server."
    }
    ~~~

2.  The endpoint you are requesting exists, but a resource cannot be located using the
    given URI. For example, trying to access an event resource with a non-existant ID such
    as /events/0000000 will result in the following response:
  
    ~~~
    {
        "error": "There is presently no resource with the given URI."
    }
    ~~~

### Server Errors

This version of the API is still under development and there may be bugs and runtime errors
encountered while processing your request. In these cases, a 500 error response will be sent
with the message below. If such a message is received, please contact a
[system administrator](mailto:dev@ticketingevents.com "Administrator Contact") with the details
of your request (endpoint, method, headers and payload), so they may reproduce and resolve the
issue.

~~~
{
  "message": "There was a server error while excuting this request. Please see system logs for details."
}
~~~

### Other Errors

Additional error responses may be received when incorrectly accessing valid API endpoints. The
errors received, and their resolution, are specific to the requested URI and HTTP Method and details
are provided with each endpoint's reference where applicable.


Version: 3.0.0
License: Apache 2.0

## Servers

QA Server
```
https://qa.ticketingevents.com/v3
```

Production Server
```
https://api.ticketingevents.com/v3
```

## Security

### SessionKey

Type: apiKey
In: header
Name: X-API-Key

## Download OpenAPI description

[TickeTing REST API v3 Reference](https://docs.ticketingevents.com/_bundle/openapi.yaml)

## Session Authentication

### Start a new API session

 - [POST /sessions](https://docs.ticketingevents.com/openapi/session-authentication/start_session.md): When provided with a valid username/email address and password, starts a new
API session, returning the associated key.

### Retrieve an active API session

 - [GET /sessions/active](https://docs.ticketingevents.com/openapi/session-authentication/continue_session.md): Returns details of the user's active API session. The session returned is
based on the key used to authenticate the request.

### End an active API session

 - [DELETE /sessions/active](https://docs.ticketingevents.com/openapi/session-authentication/end_session.md): Ends the user's active API session based on the key used to authenticate the request.

## Token Authentication

### Retrieve token key

 - [GET /tokens/{code}](https://docs.ticketingevents.com/openapi/token-authentication/retrieve_token_auth.md): Returns authentication key and netadata for an event admissions
token. Authenticating requests with the returned key will grant access to
endpoints needed for ticket redemption.

## API Integrations

### Create new integration token

 - [POST /integrations](https://docs.ticketingevents.com/openapi/api-integrations/create_integration.md): Create an API integration token that can be used to authenticate requests
instead of a session key. Integrations should be used where user interaction
is not desirable/possible or for server to server applications.

## Account Management

### List user accounts

 - [GET /accounts](https://docs.ticketingevents.com/openapi/account-management/list_accounts.md): Retrieve a list of TickeTing user accounts.

### Create a new account

 - [POST /accounts](https://docs.ticketingevents.com/openapi/account-management/create_account.md): Create a new TickeTing user account. Most user data is optional for
account creation, so there is flexibility in the stage of the
onboarding process at which data is captured.

### Retrieve account details

 - [GET /accounts/{number}](https://docs.ticketingevents.com/openapi/account-management/retrieve_account.md): Returns details of the specified user account.

### Modify account details

 - [PUT /accounts/{number}](https://docs.ticketingevents.com/openapi/account-management/update_account.md): Update the details of the specified user account

### Remove an account

 - [DELETE /accounts/{number}](https://docs.ticketingevents.com/openapi/account-management/delete_account.md): Completely remove an account from the system. An account can only be deleted
if it does not currently hold tickets to upcoming events.

### Retrieve account preferences

 - [GET /accounts/{number}/preferences](https://docs.ticketingevents.com/openapi/account-management/retrieve_account_preferences.md): Returns the user preferences for the account.

### Update account preferences

 - [PUT /accounts/{number}/preferences](https://docs.ticketingevents.com/openapi/account-management/update_account_preferences.md): Make changes to the account's user preferences

### List managed hosts

 - [GET /accounts/{number}/hosts](https://docs.ticketingevents.com/openapi/account-management/list_account_hosts.md): Retrieve a list of registered event hosts for which this user has administrative permissions.

### Lookup an account

 - [POST /lookups](https://docs.ticketingevents.com/openapi/account-management/lookup_account.md): Test the existenc of an account using its username or email address. A user role
can optionally be provided to test for the existence of accounts of a certain type.

## Account Verification

### Request verification code

 - [POST /verifications](https://docs.ticketingevents.com/openapi/account-verification/request_verification_code.md): Request that an account verification code be sent to the provided email address, if it belongs to a registered user.

### Verify account

 - [PATCH /verifications/{verification}](https://docs.ticketingevents.com/openapi/account-verification/verify_account.md): Verify the account if the verification code matches that sent to the account's email address.

## Password Reset

### Request password reset

 - [POST /resets](https://docs.ticketingevents.com/openapi/password-reset/request_reset.md): Request that a password reset code be sent to the provided email address, if it belongs to a registered user.

### Reset password

 - [PATCH /resets/{reset}](https://docs.ticketingevents.com/openapi/password-reset/reset_password.md): Change the password to the value provided if the reset code matches that sent to the account's email address.

## Account Activation

### Toggle account activation

 - [POST /accounts/{number}/toggles](https://docs.ticketingevents.com/openapi/account-activation/toggle_account.md): Deactivates the specified account if it is active, and activates
it otherwise.

### Request account deletion

 - [POST /accounts/{number}/deletions](https://docs.ticketingevents.com/openapi/account-activation/request_deletion.md): Notifies system administrators that the user would like to delete their account.
When a deletion request is submitted, the account is immediately deactivated,
and can no longer authenticate requests, pending review.

## Account Activity

### List API sessions

 - [GET /accounts/{number}/sessions](https://docs.ticketingevents.com/openapi/account-activity/list_api_session.md): Retrieve a list of API sessions opened by this user.

### View order history

 - [GET /accounts/{number}/orders](https://docs.ticketingevents.com/openapi/account-activity/view_order_history.md): Retrieve the order history of the specified account.

### Retrieve event itinerary

 - [GET /accounts/{number}/events](https://docs.ticketingevents.com/openapi/account-activity/view_event_itinerary.md): Retrieve a list of events, past and future, that the account has tickets for.

### Retrieve ticket wallet

 - [GET /accounts/{number}/tickets](https://docs.ticketingevents.com/openapi/account-activity/list_ticket_wallet.md): Retrieve a list of tickets belonging to the specified account.

### View transfer history

 - [GET /accounts/{number}/transfers](https://docs.ticketingevents.com/openapi/account-activity/view_transfer_history.md): Retrieve the transfer history of the specified account.

## Managing Host Accounts

### List event hosts

 - [GET /hosts](https://docs.ticketingevents.com/openapi/managing-host-accounts/list_hosts.md): Retrieve a list of registered event hosts that match the given criteria.

### Create an event host

 - [POST /hosts](https://docs.ticketingevents.com/openapi/managing-host-accounts/create_host.md): Create a new host which can list and promote events, sell tickets
or request add-on services through TickeTing. The authorising user account is
automatically added to the event host's list of administrators upon creation.

### Retrieve host details

 - [GET /hosts/{host}](https://docs.ticketingevents.com/openapi/managing-host-accounts/retrieve_host.md): Retrieve the registration details of the specified host.

### Update host details

 - [PUT /hosts/{host}](https://docs.ticketingevents.com/openapi/managing-host-accounts/update_host.md): Change the registered details of the specified event host

### Remove an event host

 - [DELETE /hosts/{host}](https://docs.ticketingevents.com/openapi/managing-host-accounts/delete_host.md): Completely remove a registered event host from the system. The host
will no longer be able to list or promote events, sell tickets,
or request add-on services through TickeTing. Any existing events listed
under the removed host account will still be active in the system, and any
tickets sold will remain valid.

### List hosted events

 - [GET /hosts/{host}/events](https://docs.ticketingevents.com/openapi/managing-host-accounts/list_host_events.md): Retrieve a list of all events registered by this event host.

## Working with Events

### List all published events

 - [GET /published-events](https://docs.ticketingevents.com/openapi/working-with-events/list_published_events.md): Retrieve a list of published events open to the public that match the given criteria.

### List all events

 - [GET /events](https://docs.ticketingevents.com/openapi/working-with-events/list_events.md): Retrieve a list of events matching the given criteria.

### Register an event

 - [POST /events](https://docs.ticketingevents.com/openapi/working-with-events/register_event.md): Register a new event in the TickeTing system. Once submitted for review and
approved by an administrator, the host can begin to sell tickets to the event.

### Retrieve event details

 - [GET /events/{event}](https://docs.ticketingevents.com/openapi/working-with-events/retrieve_event.md): Retrieve the registration details of the requested event

### Update event details

 - [PUT /events/{event}](https://docs.ticketingevents.com/openapi/working-with-events/update_event.md): Change the details of the requested event

### Remove an event

 - [DELETE /events/{event}](https://docs.ticketingevents.com/openapi/working-with-events/delete_event.md): Completely remove a registered event from the system. Only events that have not sold
any tickets can be deleted. If tickets have been sold, but further sales should be
prevented, an event can be unpublished or cancelled as necessary.

## Event Admissions

### Issue admission tokens

 - [POST /events/{event}/tokens](https://docs.ticketingevents.com/openapi/event-admissions/manage_admission_tokens.md): Create tokens that authorise event staff to grant admission to the event. Tokens allow event staff to redeem tickets
and admit patrons to one or more event sections. Each event has a global token that allows redemption of tickets for
all sections. Additional tokens can be created, as needed, and should be issued to event staff on a one-to-one basis.

### List admission tokens

 - [GET /events/{event}/tokens](https://docs.ticketingevents.com/openapi/event-admissions/list_event_tokens.md): Retrieve a list of tokens permitted to redeem tickets issued for this event.

### Retrieve admission token details

 - [GET /events/{event}/tokens/{token}](https://docs.ticketingevents.com/openapi/event-admissions/retrieve_admission_token.md): Retrieve the details of the specified admission token.

### Modify admission token sections

 - [PUT /events/{event}/tokens/{token}](https://docs.ticketingevents.com/openapi/event-admissions/update_admission_token.md): Update the event sections that the admission token can be used to grant entry to

### Invalidate an admission token

 - [DELETE /events/{event}/tokens/{token}](https://docs.ticketingevents.com/openapi/event-admissions/invalidate_admission_token.md): Invalidate an admission token and remove it from the event. Invalidated tokens can no longer be used
by event staff to redeem tickets and grant admission.

### Retrieve valid event tickets

 - [GET /events/{event}/tickets](https://docs.ticketingevents.com/openapi/event-admissions/list_event_tickets.md): Retrieve a detailed list of valid event tickets issued for sections that the authenticated redeemer
is authorised to admit patrons to.

### Admit event patrons

 - [POST /events/{event}/admissions](https://docs.ticketingevents.com/openapi/event-admissions/admit_event_patrons.md): Attempt to admit one or more patrons to an event based on their ticket serial numbers.
The endpoint accepts a list containing the serials of tickets to be redeemed. The system
will admit any serials that are currently valid for the event sections that the redeemer is
authorised to admit to, and return a list of those that were successfully redeemed.

### List event admissions

 - [GET /events/{event}/admissions](https://docs.ticketingevents.com/openapi/event-admissions/list_event_admissions.md): Retrieve a list of admissions to the event sections that the authenticated redeemer has access to.

## Event Reporting

### View host statistics

 - [GET /hosts/{host}/statistics](https://docs.ticketingevents.com/openapi/event-reporting/view_host_statistics.md): View high-level statistics for a host including total revenues, tickets sold,
events listed and unique customers.

### View event statistics

 - [GET /events/{event}/statistics](https://docs.ticketingevents.com/openapi/event-reporting/view_event_statistics.md): View high-level statistics for an event including revenues, tickets sold,
ticket capacity and total orders.

### Report event sales

 - [GET /events/{event}/sales](https://docs.ticketingevents.com/openapi/event-reporting/report_event_sales.md): Generate a summary report of ticket sales for this event using the given criteria

## Placing an Order

### List orders

 - [GET /orders](https://docs.ticketingevents.com/openapi/placing-an-order/list_orders.md): Retrieve a list of orders matching the given criteria.

### Place a new order

 - [POST /orders](https://docs.ticketingevents.com/openapi/placing-an-order/place_order.md): Place a new order for one or more tickets. A single order can include multiple
ticket types of a single event, or from multiple events. When a new order is created
tickets are reserved for a fixed period of time until the order is settled, cancelled
or times out.

If the tickets being ordered are free (i.e. the order total is $0.00), the order is
fuliflled immediately and tickets delivered to the customer's account.

### Retrieve order details

 - [GET /orders/{order}](https://docs.ticketingevents.com/openapi/placing-an-order/retrieve_order.md): Retrieve the details of the requested order

### Cancel an order

 - [DELETE /orders/{order}](https://docs.ticketingevents.com/openapi/placing-an-order/cancel_order.md): Cancel an existing order. Any reserved tickets are immediately released. An order
can only be cancelled if it has not already been settled or timed out.

## Order Settlement

### Attempt payment

 - [POST /orders/{order}/payments](https://docs.ticketingevents.com/openapi/order-settlement/settle_order.md): Attempt to settle a pending order by credit card payment. Payment can only be attempted
once an order has been placed, but before it has timed out. Payment can no longer be
attempted once an order has been fulfilled, refunded or cancelled.

If the tickets being ordered are free (i.e. the order total is $0.00), the order does
not require settlement, and will be fulfilled immediately without payment.

### Refund order

 - [POST /orders/{order}/refunds](https://docs.ticketingevents.com/openapi/order-settlement/refund_order.md): Attempt to refund an order, reversing the attached credit card payment. Only fulfilled orders can be 
refunded and each order can only be sucessfully refunded once. Orders for free tickets or ones that
have not been fulfilled, cannot be refunded.

## Ticket Transfers

### Initiating a transfer

 - [POST /transfers](https://docs.ticketingevents.com/openapi/ticket-transfers/initiate_transfer.md): Initiate a transfer of one or more tickets from the requesting user
to another TickeTing user. Initiating a transfer, does not automatically
move tickets between accounts, but instead sends a transfer request. This request
must first be claimed at which time the tickets themselves are transferred.
If the transfer request is cancelled or rejected, no tickets change hands.

One or more tickets, for one or multiple events, can be sent in a single transfer. 
Tickets that are part of an open transfer (not yet claimed, canclled or rejected)
enter into a pending state in which they cannot be redeemed, only becoming usable
again once a decision is taken on the transfer.

### Retrieve transfer details

 - [GET /transfers/{transfer}](https://docs.ticketingevents.com/openapi/ticket-transfers/retrieve_transfer.md): Retrieve the details of the requested transfer

### Cancel a transfer

 - [DELETE /transfers/{transfer}](https://docs.ticketingevents.com/openapi/ticket-transfers/cancel_transfer.md): Cancel a pending transfer. A transfer can be cancelled by either its sender or
its recipient before it is claimed. Any pending tickets attached to the transfer
are immediately released. A transfer can only be cancelled if it has not yet
been claimed, or previously cancelled.

### Claim a transfer

 - [POST /transfers/{transfer}/claims](https://docs.ticketingevents.com/openapi/ticket-transfers/claim_transfer.md): Claim a pending transfer. Once claimed, any tickets attached to the transfer are moved
from the sender's account to the recipient's and returned to a usable state. Only a
transfer's recipient can claim a transfer, and a transfer can no longer be claimed once
it has been cancelled or claimed previously.

## Region Management

### List supported regions

 - [GET /regions](https://docs.ticketingevents.com/openapi/region-management/list_regions.md): Retrieve a list of supported regions where events can be staged.

### Add a supported region

 - [POST /regions](https://docs.ticketingevents.com/openapi/region-management/add_region.md): Add a supported region to the TickeTing system. Any venue created needs to reference the region
in which it is located. Events staged at this venue will be grouped within the related region,
and are displayed to users based on their regional preference.

### Retrieve region details

 - [GET /regions/{region}](https://docs.ticketingevents.com/openapi/region-management/retrieve_region.md): Retrieve the details of the specified region.

### Modify region details

 - [PUT /regions/{region}](https://docs.ticketingevents.com/openapi/region-management/update_region.md): Update the details of the specified region

### Remove a supported region

 - [DELETE /regions/{region}](https://docs.ticketingevents.com/openapi/region-management/remove_region.md): Completely remove a supported region from the system. A region can only be deleted
if it has no venues associated to it.

## Venue Management

### List event venues

 - [GET /venues](https://docs.ticketingevents.com/openapi/venue-management/list_venues.md): Retrieve a list of approved venues at which events can be hosted.

### Create an event venue

 - [POST /venues](https://docs.ticketingevents.com/openapi/venue-management/create_venue.md): Create an approved venue that can stage events. Once created, the venue can be
selected as hosting new events added to the system.

### Retrieve event venue details

 - [GET /venues/{venue}](https://docs.ticketingevents.com/openapi/venue-management/retrieve_venue.md): Retrieve the details of the specified event venue.

### Modify event venue details

 - [PUT /venues/{venue}](https://docs.ticketingevents.com/openapi/venue-management/update_venue.md): Update the details of the specified event venue

### Remove an event venue

 - [DELETE /venues/{venue}](https://docs.ticketingevents.com/openapi/venue-management/delete_venue.md): Completely remove an event venue from the system. A venue can only be deleted
if no events are or have been staged there.

## Category Management

### List event categories

 - [GET /categories](https://docs.ticketingevents.com/openapi/category-management/list_categories.md): Retrieve a list of event categories under which events can be classified.

### Create an event category

 - [POST /categories](https://docs.ticketingevents.com/openapi/category-management/create_category.md): Create an event category (and its associated subcategories). Once created, the category 
(and one of its subcategories) can be used to classify events.

### Retrieve category details

 - [GET /categories/{category}](https://docs.ticketingevents.com/openapi/category-management/retrieve_category.md): Retrieve the details of the specified event category.

### Modify category details

 - [PUT /categories/{category}](https://docs.ticketingevents.com/openapi/category-management/update_category.md): Update the details of the specified event category

### Remove a category

 - [DELETE /categories/{category}](https://docs.ticketingevents.com/openapi/category-management/delete_category.md): Completely remove an event category from the system. A category can only be deleted
if it is not associated with any events.

## Reviewing Content

### List submissions

 - [GET /submissions](https://docs.ticketingevents.com/openapi/reviewing-content/list_submissions.md): Retrieve a list of content submitted by hosts for review, optionally filtered by type.

### Retrieve submission details

 - [GET /submissions/{submission}](https://docs.ticketingevents.com/openapi/reviewing-content/retrieve_submission.md): Retrieve the details of the specified content submission

### Decide on a submission

 - [DELETE /submissions/{submission}](https://docs.ticketingevents.com/openapi/reviewing-content/decide_on_submission.md): Decide whether to approve or reject the submitted content. If approved, the content will be
made visible to the public, across all TickeTing platforms. If rejected, the content will revert to a draft
and only be visible to administrators of the host who submitted it.

## Transaction Reports

### Generate transaction report

 - [GET /transactions](https://docs.ticketingevents.com/openapi/transaction-reports/transaction_report.md): Retrieve a list of transactions matching the given criteria.

## Default Values

### Retrieve a list of countries

 - [GET /countries](https://docs.ticketingevents.com/openapi/default-values/retrieve_countries.md): Retrieve a list of country names to be used in association with
user accounts, events, hosts, etc.