Requests and responses

Learn how Livestorm's REST API accepts requests and sends back responses


Livestorm's REST API follows the JSON API conventions, which means that you'll have to encode your requests in JSON. Additionally, don't forget to add the Content-Type: application/json header to your HTTP requests. All requests must be sent over HTTPS.


Similarly, API responses will be JSON-encoded. Standard HTTP codes will apply:

  • 2xx for successful requests
    • 200 for successful GET, PUT, and PATCH calls.
    • 201 for successful POST calls (created).
    • 204 for successful DELETE calls (no content).
  • 4xx for user-related errors:
    • 400 errors when the payload (body/query params) is invalid or incorrectly formatted.
    • 401 errors when your authentication isn't valid (missing or invalid Authorization header value).
    • 402 errors are related to your billing preferences and happen when you reached your monthly active contacts allowance. You need to upgrade your plan to unlock new active contacts.
    • 403 errors when the resource you're trying to access isn't included in your scopes (API token scopes or OAuth2 access token scopes) or if your account hasn't been validated.
    • 404 errors when the resource you're trying to access doesn't exist.
    • 409 errors when the resource already exists (usually when someone is already registered to a session).
    • 422 errors when the payload is valid but cannot be processed by Livestorm due to incorrect business logic.
    • 429 errors when your API rate limits have been reached.
  • 5xx for unexpected server errors. Please get in touch with us if this happens.