API reference

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:


Authentication

Each request to one of the API endpoints must contain a token: an API key for your own account, or an access token from OAuth 2.0 for an app that other users connect to. See Authentication for which one to use.

Include the token 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-or-access-token}"

Each endpoint lists the OAuth scope it needs. API keys have access to everything the user can access, without scopes.

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.

Changing the slug

If you change the slug of your organisation in the Hipsy dashboard, endpoints that use the old slug stop working. Use the ID of the organisation if you want your integration to keep working after a slug change.

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.

Status codeDescription
401The API key or access token is missing, invalid, expired or revoked.
403The user doesn't have access to the requested organisation, or the OAuth access token misses the scope or wasn't granted for this organisation.
404The organisation doesn't exist.
429Too many requests. Wait a moment before you send the next request.
Previous
OAuth 2.0