Getting started

Hipsy has a small set of APIs to connect your data to your own website or other third party applications. Currently we provide the following API resources:

• Current account
• List organisations
• List events
• List orders
• List reviews

Using the API key

Each request to one of the API endpoints must contain an API key, which you can create in your Hipsy dashboard.

Include the key in the Authorization header as a Bearer token:

curl https://api.hipsy.nl/v1/organisations/index \
   -H "Accept: application/json" \
   -H "Authorization: Bearer {api-key}"

Always send the Accept: application/json header, so that errors are returned as JSON as well.

Organisation endpoints

Most endpoints return data of one organisation, for example /v1/organisation/{organisation}/events. For {organisation} you can use either the slug or the ID of the organisation. Use the List organisations endpoint to find both.

Dates

All dates are returned in the ISO 8601 format in UTC, for example 2023-03-01T20:00:00.000000Z.

Pagination

Endpoints that return a list are paginated. Use the page parameter to request the next page. Besides the data array, the response contains a links object with the URLs of the first, last, previous and next page, and a meta object with the totals:

{
    "data": [...],
    "links": {
        "first": "https://api.hipsy.nl/v1/organisation/my-organisation/events?page=1",
        "last": "https://api.hipsy.nl/v1/organisation/my-organisation/events?page=3",
        "prev": null,
        "next": "https://api.hipsy.nl/v1/organisation/my-organisation/events?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "path": "https://api.hipsy.nl/v1/organisation/my-organisation/events",
        "per_page": 25,
        "to": 25,
        "total": 61
    }
}

The meta object also contains a links array with the page links, which is left out here.

Rate limit

You can send up to 120 requests per minute per user. If you send more, the API returns status code 429 until the minute has passed.

Errors

If a request fails, the API returns one of the following status codes with a JSON body that contains a message.