Get started — Masterconf API

The Masterconf API gives your own servers read-only access to your organization’s events, registrations, calls for papers and papers. Every request is an HTTPS GET to https://api.masterconf.com/v1.

Create an API key

An administrator of your organization creates keys in the console, under Integrations (« Intégrations »).

Scopes. Pick only what your application reads: events_read, registrations_read, calls_for_papers_read.
Expiry. Every key expires. Choose a date at most 366 days away.
Shown once. The key appears a single time, right after you create it. Copy it into your secret manager straight away: nobody can display it again, not even an administrator.

A key starts with mcf_. Treat it like a password.

Authenticate

Send the key in the Authorization header, in exactly this form:

Authorization: Bearer mcf_your_key

Never put a key in a URL, and never in a browser or a mobile app. The API is for servers: it answers no browser (CORS) request.

Make your first call

GET/v1/account needs no particular scope. It tells you which organization and which key the request used.

Request

curl

curl -G https://api.masterconf.com/v1/account \
  -H "Authorization: Bearer mcf_your_key"

JavaScript

const res = await fetch("https://api.masterconf.com/v1/account", {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.masterconf.com/v1/account",
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

Response

{
  "id": "ORG-7b2c9e40-1a5d-4c83-9f6e-3d8a0b4c2e71",
  "object": "account",
  "api_key": {
    "id": "APIK-4f8a2c1e-9b3d-4e6a-8c7f-2a1e5d9b0c34",
    "scopes": [
      "calls_for_papers_read",
      "events_read",
      "registrations_read"
    ],
    "expires_at": 1824076800
  }
}

If you get 401 api_key_invalid instead, check that the header is exactly as above.

List the registrations of an event

First find the id of an event with GET/v1/events:

Request

curl

curl -G https://api.masterconf.com/v1/events \
  -H "Authorization: Bearer mcf_your_key"

JavaScript

const res = await fetch("https://api.masterconf.com/v1/events", {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.masterconf.com/v1/events",
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

Then list its registrations with GET/v1/registrations. The event parameter is required.

Request

curl

curl -G https://api.masterconf.com/v1/registrations \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "event=EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30"

JavaScript

const params = new URLSearchParams({
  "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
});

const res = await fetch(`https://api.masterconf.com/v1/registrations?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.masterconf.com/v1/registrations",
    params={"event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

Response

{
  "object": "list",
  "url": "/v1/registrations",
  "has_more": true,
  "data": [
    {
      "id": "SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612",
      "object": "registration",
      "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
      "status": "validated",
      "role": "attendee",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada.lovelace@example.com",
      "ticket": {
        "name": "Full pass"
      },
      "checkin": {
        "checked_in": true,
        "last_checked_in_at": 1810119600
      },
      "created": 1795521600,
      "updated": 1810119600
    }
  ]
}

Walk through every page

A list returns a page of objects, newest first, and has_more. While has_more is true, ask for the next page with starting_after set to the id of the last object you received:

Request

curl

curl -G https://api.masterconf.com/v1/registrations \
  -H "Authorization: Bearer mcf_your_key" \
  --data-urlencode "event=EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30" \
  --data-urlencode "starting_after=SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612"

JavaScript

const params = new URLSearchParams({
  "event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30",
  "starting_after": "SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612",
});

const res = await fetch(`https://api.masterconf.com/v1/registrations?${params}`, {
  headers: { Authorization: "Bearer mcf_your_key" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.masterconf.com/v1/registrations",
    params={"event": "EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30", "starting_after": "SUB-8c3e2a71-0f4b-4d6a-b5e9-27c1d9a4e612"},
    headers={"Authorization": "Bearer mcf_your_key"},
)
data = res.json()

Pagination explains the rest: page size, going backwards, and keeping a copy in sync.

Next steps

Authentication: scopes, expiry and revocation.
Handling errors: what to do with each kind of error.
The API reference: every object and operation.