Getting Started

Introduction

Matchbook provides a RESTful API to facilitate integration between tools and applications and our Betting Exchange. RESTful APIs are HTTP based meaning that any tools and programming languages capable of making HTTP requests can use the Matchbook API.

The key characteristics of the API include:

  • A resource-oriented URL structure
  • Supports HTTP verbs including GET, PUT, POST and DELETE
  • Makes full use of HTTP response codes such as 2xx Successful, 3xx Redirection, 4xx Client Error, and 5xx Server Error
  • Observation of HTTP caching features including the cache-control directive

Data Format

The API supports two data formats, XML and JSON.

The desired response data format is specified by setting the Accept HTTP header to either "application/xml" or "application/json". Responses from the Matchbook API will include the Content-Type header with the value of "application/xml" or "application/json" to indicate the data format contained in the response. Requests that include a payload such as login and submit offers require the Content-Type header to specify the data format of the request body.

Matchbook recommends the use of JSON. It is a more compact format and will yield better response times due to its smaller size.

Security / Authentication

All requests to the Matchbook API should use https. The Matchbook servers will redirect http requests to https.

Matchbook provides a login API that returns a session token value in the response and in a HTTP cookie called "session-token". All subsequent requests to the other API endpoints should include this session token as either a cookie called "session-token" or a HTTP header called "session-token".

Many HTTP clients automatically handle cookies. If using a client that does then the session-token cookie will be automatically included with all requests after making the initial login request.

Localisation

Matchbook supports the use of multiple currencies, odds types and exchange types. The API will select defaults for each of these based on the most commonly used types in the region the API requests originate from. It is possible to override these defaults by providing values for currency, odds-type and exchange-type parameters to the relevant API endpoints. Details are included in the API reference for each endpoint where these are supported.

Error Handling

The Matchbook API uses standard HTTP status codes to indicate successful or error responses. The most common status codes are listed below.

Status Code

Status Line

Description

200

OK

Successful request.

301

Moved Permanently

The resource has moved to a new location permanently.

302

Moved Temporarily

The resource has moved to a new location temporarily.

400

Bad Request

The request was rejected. This could indicate missing headers or fields, a badly formatted request body or that some condition of the system did not permit the request such as sending a submit offers request to try and bet on a closed market.

401

Unauthorized

The request requires a valid session. Login via the login API and include the session-token cookie or header with the request.

403

Forbidden

The account does not have sufficient permission to access the resource.

404

Not Found

The resource / API endpoint does not exist.

405

Method Not Allowed

The resource / endpoint exists but the HTTP verb (GET, POST, PUT, DELETE) is not valid for this endpoint.

500

Internal Server Error

An error has occurred processing the request on the Matchbook servers.

502

Bad Gateway

A server error (possibly a timeout) has occurred processing the request on the Matchbook servers.

503

Service Unavailable

The service is temporarily unavailable due to a technical problem.

504

Gateway Timeout

A timeout has occurred processing the request on the Matchbook servers.

In addition to the status code error responses will also include a response body containing more detailed information e.g.

{
  "errors": [{
    "messages": ["Username or password are incorrect."]
  }]
}
<response>
  <errors>
    <error>
      <messages>Username or password is incorrect.</messages>
    </error>
  </errors>
</response>

Compression

The Matchbook API supports optional compressing of the response data using GZIP compression. It can be enabled by including the HTTP Accept-Encoding header with a value of "gzip" on each request. The response will include the HTTP Content-Encoding header with a value of "gzip" to indicate that the response is compressed.

Matchbook recommends enabling compression as it makes the response size smaller which will result in lower bandwidth usage and faster response times.