Check-in

This page describes special APIs built for ticket scanning apps. For managing check-in configuration or other operations, please also see Check-in lists. The check-in list API also contains endpoints to obtain statistics or log failed scans.

Changed in version 4.12: The endpoints listed on this page have been added.

Changed in version 4.18: The source_type parameter has been added.

Checking a ticket in

POST /api/v1/organizers/(organizer)/checkinrpc/redeem/

Tries to redeem an order position, i.e. checks the attendee in (or out). This is the recommended endpoint to use if you build any kind of scanning app that performs check-ins for scanned barcodes. It is safe to use with untrusted inputs in the secret field.

This endpoint supports passing multiple check-in lists to perform a multi-event scan. However, each check-in list passed needs to be from a distinct event.

Query Parameters:

  • expand (string) – Expand a field inside the position object into a full object. Currently subevent, item, variation, and answers.question are supported. Can be passed multiple times.

Request JSON Object:

  • secret (string) – Scanned QR code corresponding to the secret attribute of a ticket.

  • source_type (string) – Type of source the secret was obtained form. Defaults to "barcode".

  • lists (array) – List of check-in list IDs to search on. No two check-in lists may be from the same event.

  • type (string) – Send "exit" for an exit and "entry" (default) for an entry.

  • datetime (datetime) – Specifies the datetime of the check-in. If not supplied, the current time will be used.

  • force (boolean) – Specifies that the check-in should succeed regardless of revoked barcode, previous check-ins or required questions that have not been filled. This is usually used to upload offline scans that already happened, because there’s no point in validating them since they happened whether they are valid or not. Defaults to false.

  • questions_supported (boolean) – When this parameter is set to true, handling of questions is supported. If you do not implement question handling in your user interface, you must set this to false. In that case, questions will just be ignored. Defaults to true.

  • ignore_unpaid (boolean) – Specifies that the check-in should succeed even if the order is in pending state. Defaults to false and only works when include_pending is set on the check-in list.

  • answers (object) – If questions are supported/required, you may/must supply a mapping of question IDs to their respective answers. The answers should always be strings. In case of (multiple-)choice-type answers, the string should contain the (comma-separated) IDs of the selected options.

  • nonce (string) – You can set this parameter to a unique random value to identify this check-in. If you’re sending this request twice with the same nonce, the second request will also succeed but will always create only one check-in object even when the previous request was successful as well. This allows for a certain level of idempotency and enables you to re-try after a connection failure.

Response JSON Object:

  • status (string) – "ok", "incomplete", or "error"

  • reason (string) – Reason code, only set on status "error", see below for possible values.

  • reason_explanation (string) – Human-readable explanation, only set on status "error" and reason "rules", can be null.

  • position (object) – Copy of the matching order position (if any was found). The contents are the same as the Order position resource, with the following differences: (1) The checkins value will only include check-ins for the selected list. (2) An additional boolean property require_attention will inform you whether either the order or the item have the checkin_attention flag set. (3) If attendee_name is empty, it may automatically fall back to values from a parent product or from invoice addresses.

  • require_attention (boolean) – Whether or not the require_attention flag is set on the item or order.

  • checkin_texts (list) – List of additional texts to show to the user.

  • list (object) – Excerpt of information about the matching check-in list (if any was found), including the attributes id, name, event, subevent, and include_pending.

  • questions (object) – List of questions to be answered for check-in, only set on status "incomplete".

Example request:

POST /api/v1/organizers/bigevents/checkinrpc/redeem/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

{
  "secret": "M5BO19XmFwAjLd4nDYUAL9ISjhti0e9q",
  "source_type": "barcode",
  "lists": [1],
  "force": false,
  "ignore_unpaid": false,
  "nonce": "Pvrk50vUzQd0DhdpNRL4I4OcXsvg70uA",
  "datetime": null,
  "questions_supported": true,
  "answers": {
    "4": "XS"
  }
}

Example successful response:

HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json

{
  "status": "ok",
  "position": {
    …
  },
  "require_attention": false,
  "checkin_texts": [],
  "list": {
    "id": 1,
    "name": "Default check-in list",
    "event": "sampleconf",
    "subevent": null,
    "include_pending": false
  }
}

Example response with required questions:

HTTP/1.1 400 Bad Request
Content-Type: text/json

{
  "status": "incomplete",
  "position": {
    …
  },
  "require_attention": false,
  "checkin_texts": [],
  "list": {
    "id": 1,
    "name": "Default check-in list",
    "event": "sampleconf",
    "subevent": null,
    "include_pending": false
  },
  "questions": [
    {
      "id": 1,
      "question": {"en": "T-Shirt size"},
      "type": "C",
      "required": false,
      "items": [1, 2],
      "position": 1,
      "identifier": "WY3TP9SL",
      "ask_during_checkin": true,
      "show_during_checkin": true,
      "options": [
        {
          "id": 1,
          "identifier": "LVETRWVU",
          "position": 0,
          "answer": {"en": "S"}
        },
        {
          "id": 2,
          "identifier": "DFEMJWMJ",
          "position": 1,
          "answer": {"en": "M"}
        },
        {
          "id": 3,
          "identifier": "W9AH7RDE",
          "position": 2,
          "answer": {"en": "L"}
        }
      ]
    }
  ]
}

Example error response (invalid ticket):

HTTP/1.1 404 Not Found
Content-Type: text/json

{
  "detail": "Not found.",
  "status": "error",
  "reason": "invalid",
  "reason_explanation": null,
  "require_attention": false,
  "checkin_texts": []
}

Example error response (known, but invalid ticket):

HTTP/1.1 200 OK
Content-Type: text/json

{
  "status": "error",
  "reason": "unpaid",
  "reason_explanation": null,
  "require_attention": false,
  "checkin_texts": [],
  "list": {
    "id": 1,
    "name": "Default check-in list",
    "event": "sampleconf",
    "subevent": null,
    "include_pending": false
  },
  "position": {
    …
  }
}

Possible error reasons:

  • invalid - Ticket is not known.

  • unpaid - Ticket is not paid for.

  • blocked - Ticket has been blocked.

  • invalid_time - Ticket is not valid at this time.

  • canceled – Ticket is canceled or expired.

  • already_redeemed - Ticket already has been redeemed.

  • product - Tickets with this product may not be scanned at this device.

  • rules - Check-in prevented by a user-defined rule.

  • ambiguous - Multiple tickets match scan, rejected.

  • revoked - Ticket code has been revoked.

  • unapproved - Order has not yet been approved.

  • error - Internal error.

In case of reason rules and invalid_time, there might be an additional response field reason_explanation with a human-readable description of the violated rules. However, that field can also be missing or be null.

Parameters:

  • organizer – The slug field of the organizer to fetch

Status Codes: