# Developer API

Source: https://blocklive.io/docs/developers

Read your events, ticket types, attendees and check-ins from your own app: a
door or badge app, a CRM sync, a dashboard.

> The developer API is in a pilot. Blocklive switches developer access on for
> an organization or a team. To take part, email
> [support@blocklive.io](mailto:support@blocklive.io).

## What it does

-   It reads. Every endpoint is a `GET` under `https://blocklive.io/api/v1` and
    answers JSON.
-   It covers events, ticket types, attendees (one row per ticket holder) and
    the door's check-ins and check-outs.
-   It doesn't check guests in, add guests or change anything. Check-in stays in
    Blocklive's door app.

## Get a key

An API key comes from the organizer: an admin of the organization or team, in
Blocklive's admin, on its **Developer** page. When the key is made, the
organizer chooses which events it reads and which attendee details it gets.

The key is shown once. Blocklive keeps only a hash of it, so a lost key can't be
shown again: ask the organizer for a new one.

## Authenticate

Send the key as a bearer token on every request:

```http
Authorization: Bearer bl_live_<id>_<secret>
```

```sh
curl -H "Authorization: Bearer $BLOCKLIVE_API_KEY" https://blocklive.io/api/v1/events
```

> **Warning:** Keep the key on your server, in your app's secret settings.
> Never put it in a browser, a phone app or a repository. Anyone with the key
> can read what it reads.

-   A revoked or expired key gets `401 unauthorized`.
-   Keys made outside production start with `bl_test_` and only work there.

## What a key reads

Every key reads **events, ticket types and attendees by an anonymous ID**.
Attendee details are included only if the organizer shared them with the key:

| Detail                  | Field in the API      | Needs                   |
| ----------------------- | --------------------- | ----------------------- |
| Email address           | `email`               |                         |
| Full name               | `name`                |                         |
| Company                 | `company`             |                         |
| Job title               | `job_title`           |                         |
| Ticket types and access | `ticket_entitlements` |                         |
| Ticket type names       | `ticket_type_names`   | Ticket types and access |
| Purchase status         | `purchase_state`      |                         |
| Venue check-in          | `checkin_state`       |                         |
| Check-in time           | `checkin_time`        | Venue check-in          |

Each answer lists what your key reads for that event in `shared_fields`.

## Endpoints

| Path                                         | Returns                                                  |
| -------------------------------------------- | -------------------------------------------------------- |
| `/events`                                    | The events your key can read, newest first               |
| `/events/{event_id}/ticket-types`            | The event's ticket types                                 |
| `/events/{event_id}/attendees`               | One row per ticket holder, with only the details shared  |
| `/events/{event_id}/attendees/{attendee_id}` | One attendee                                             |
| `/events/{event_id}/check-ins`               | Check-ins and check-outs in order (needs venue check-in) |

Fields, examples and paging are in [read endpoints](https://blocklive.io/docs/developers/reads). The rate limit
and every error code are in [limits and errors](https://blocklive.io/docs/developers/limits-and-errors).

## Privacy

-   A key reads only the details shared with it, only for its events, and only
    while developer access is on.
-   Attendees are identified by anonymous IDs made for each key and event.
-   Blocklive logs each request's time, key, endpoint, status and duration for
    90 days, never the data it returned.

## Help

Email [support@blocklive.io](mailto:support@blocklive.io) with the `request_id`
of any error.