Skip to main content
In this guide you create an out-of-home (OOH) pre-test and download the PDF. The values in the examples are made up.
The API key is a server secret. Keep it in an environment variable on your back end. Never put it in browser code, in a mobile app or in a repository.

1. Create the key in the dashboard

  1. Sign in to the Unite dashboard with a workspace administrator account.
  2. Open the workspace administration area and go to API keys.
  3. Click Create key.
  4. Give it a name (for example, “CRM integration”), choose the Read pre-tests and Create pre-tests permissions and set the expiry.
  5. Click Create key and copy the value. It is shown only once.
If the screen says the API is not yet enabled for the workspace, contact the Unite team. In the examples below, the key lives in the UNITE_API_KEY variable. The value has the format unite_live_YOUR_KEY_HERE.
The blocks for each language form a single script: you can paste steps 2 to 7 into one file, in order. In curl, each step stores the values the next one needs in shell variables (requires jq). The JavaScript examples use node 18 or newer, as an ES module (.mjs).

2. Read the catalog

The catalog lists the OOH formats, the digital platforms and the workspace brands. Keep the key of the format you will use.

3. Request the upload address

Provide the file type and size. The response contains the uploadId and an upload URL valid for 15 minutes.
Response (made-up values; the real uploadUrl is long and changes with every request):

4. Upload the file

Make a PUT of the file to the uploadUrl, with all the returned headers, with exactly the same values. This call does not carry the API key. See the details in File uploads.

5. Create the pre-test

Send the uploadId and the channel. The Idempotency-Key header is required: use a new value for each pre-test and reuse it only to repeat the same call. See Idempotency.
The response is 202 and carries the Location header with the pre-test address.

6. Poll until completed

Poll every 10 seconds or more. With completed, the result field carries the score, pillars and findings (see Results). With failed, the error.code field gives the reason. If it ends in failed, stop here: there is no PDF to download.

7. Download the PDF

The PDF is generated on demand. If it is still being generated, the response is 202 with Retry-After: wait that many seconds and try again. With 200 and status: "ready", download the file from url. That second call is a plain GET on the url, without the API key.
Fetch the link when you need the file, and do not count on the URL staying the same: request the PDF again instead of storing the link.

Next steps