Clone wiki

API-2.0 / General_notes_old

Following description DEPRECATED, please use General notes instead

"X-API-Key" request header

All API requests require valid API key in X-API-Key HTTP header. Live or sandbox API key can be obtained on client Settings/General page, API Access tab.

For example, to add this header with curl:

curl -H 'X-API-Key: test_8kBFkhmf8TA7TZyQBh' ...

"X-Authentication" request header

Some API requests require authentication in the form of X-Authentication HTTP header. This header value should have format "email:token" where token is a single_access_token returned by Login request. Curl example:

curl -H 'X-Authentication:' ...

API versioning

Specific API version can be selected with "Accept" requst header with "application/launch27.{version}" value.

To use version 2.0, the following header must be present:

Accept: application/launch27.v2

If Accept header does not specify version, version 1.0 is used.

Dates and datetimes format

Where not otherwise specified, all date and datetime values are formatted and expected in ISO 8601 format without time zone info:

  • 2015-01-31 - example date parameter for Get spots
  • 2015-01-31T14:30 - example booking service_date parameter for Create booking

All dates and datetmes are in client's timezone.

Error reporting

If API key is not provided or invalid, all requests return 406 'Not acceptable' status code and additional JSON payload describing what caused the error, for example

{"code": 406, "message": "not acceptable", "errors": ["Missing API key"] }

If request requires authentication and authentication info is missing or invalid, the request return 401 Unauthorized response.

If request finishes with error, error info is returned as JSON payload in one of the following formats:

  • responses with status codes 500 (internal server error), 403 (forbidden), 404 (not found) return status code with short message, f.i:
{"code": 404, "message": "resource not found"}
  • for create/update actions, resource validation errors are returned with status 406 and error(s) description in the following formats:

{"code": 406,
   "message": "not acceptable",
   "errors": {
     "service_id":["can't be blank"],
     "email":["can't be blank"]
-- when some of the fields have invalid values

{"code": 406,
  "message": "not acceptable",
  "errors": ["You cannot book an appointment for selected service date"]
-- when resource itself is invalid or cannot be created/updated.