Skip to main content
Integrations

API and webhooks

Create an API key, and what the public API lets you do on a paper exam: copies, scan import, enrollments and grades.

Written By Florian Barral

Last updated 9 days ago

The public API lets your tools (information system, scripts, intranet) read your paper exams, download the copies, send the scans and retrieve the grades. It is reserved for organization administrators.

Create an API key

  1. Click your name at the bottom of the sidebar, then Settings.

  2. In the Administration section, open API.

  3. In API keys, click New key.

  4. Give it a Key name that helps you recognize it, then click Create key.

  5. Copy the Client ID and the Client secret, then click I saved my credentials.

The client secret is only shown once. Store it in a secret manager. If you lose it, delete the key and create a new one.

A key gives access to all of the organization's data. To cut off access, click Delete: the integrations using it stop working immediately.

Authenticate

Your tool exchanges the client ID and the client secret for an access token (OAuth 2.0, client_credentials), then sends it with every call. The Read more link on the API keys card opens the full API documentation: addresses, parameters and examples.

What the API lets you do on a paper exam

Need

With the API

Find your paper exams

List exams, filtering on the paper type.

Enroll participants

Add, edit or remove enrolled participants, up to 50 per call. No email is sent to them.

Follow the copies' preparation

Read the copy type (nominative or anonymous), the number of copies and the generation status.

Download the copies

Retrieve the PDF of all copies, individual copies, answer sheets or question sheets, once generated.

Import the scans

Send a PDF of scans (20 MB maximum per file). Imports add up, and analysis works as in the app.

Retrieve the grades

Read each participant's final grade.

Create the exam, set up the copies and start their generation in Papeez: the API reads this state and serves the files, but does not create paper exams. Pages the analysis could not match to a participant are handled in Papeez: see Import the scans.

Webhooks

On the same page, the Webhooks card sends your organization's events to your servers as they happen: New webhook, then the Destination URL (https) and the Events to receive. For a paper exam, the useful events concern the emails sent to participants (sent, delivered, opened…). There is no event yet for scans or grades: query the API to follow the scan analysis.

API keys are available with all plans. Webhooks are not included in every plan: if that is the case for yours, Papeez tells you when you create one.

Frequently asked questions

The Administration section of the settings is reserved for organization administrators.

On an exam with anonymous copies, enroll the participants first: Papeez needs the list of enrolled participants to match each copy. See Nominative or anonymous copies.

The files only exist once the copies have been generated in Papeez. See Generate the copies to print.