Retrieve delivery proofs

Before you start

Run these examples on a trusted server with TAROT_API_KEY set in its environment. Use X-Tarot-API-Key on every request. Never expose the key in client-side code, including browser or mobile app code. See Getting an API key.

After dispatch

Once your runs are dispatched and drivers begin recording deliveries, retrieve their proof information using the calls below. Ensure you have the scenario’s numeric ID, from POST /v3/core/jobs/bulk_create or GET /v3/core/scenarios. These examples assume it is available in the SCENARIO_ID environment variable.

Looking for planned runs?

See the Retrieve Planned Runs guide.

Retrieve job proofs

Job proofs describe what happened at a stop: signature, photos, comments, coordinates, and delivery outcome where recorded. Your key needs proof-read permission.

GET /v3/core/job_proofs?scenario_ids={ID}&page=1&per_page=100

curl --fail-with-body -X GET "https://api.optimiser.app/v3/core/job_proofs?scenario_ids=${SCENARIO_ID}&page=1&per_page=100" \
  -H "X-Tarot-API-Key: $TAROT_API_KEY"

import os, requests

scenario_id = os.environ["SCENARIO_ID"]

response = requests.get(
    f"https://api.optimiser.app/v3/core/job_proofs?scenario_ids={scenario_id}&page=1&per_page=100",
    headers={"X-Tarot-API-Key": os.environ["TAROT_API_KEY"]},
    timeout=60,
)
response.raise_for_status()
print(response.json())

const response = await fetch(`https://api.optimiser.app/v3/core/job_proofs?scenario_ids=${process.env.SCENARIO_ID}&page=1&per_page=100`, {
  method: "GET",
  headers: {
    "X-Tarot-API-Key": process.env.TAROT_API_KEY,
  },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

Replace the scenario filter with the desired filter; these are alternatives, not a request to send every filter. See JobProofSchema schema reference.

Retrieve unit proofs

Unit proofs capture parcel-level events such as barcode scans and delivery or rejection outcomes. Unit operations require the organisation’s units module as well as proof-read permission. Supply at least one filter.

GET /v3/core/unit_proofs?scenario_ids={ID}&page=1&per_page=100

curl --fail-with-body -X GET "https://api.optimiser.app/v3/core/unit_proofs?scenario_ids=${SCENARIO_ID}&page=1&per_page=100" \
  -H "X-Tarot-API-Key: $TAROT_API_KEY"

import os, requests

scenario_id = os.environ["SCENARIO_ID"]

response = requests.get(
    f"https://api.optimiser.app/v3/core/unit_proofs?scenario_ids={scenario_id}&page=1&per_page=100",
    headers={"X-Tarot-API-Key": os.environ["TAROT_API_KEY"]},
    timeout=60,
)
response.raise_for_status()
print(response.json())

const response = await fetch(`https://api.optimiser.app/v3/core/unit_proofs?scenario_ids=${process.env.SCENARIO_ID}&page=1&per_page=100`, {
  method: "GET",
  headers: {
    "X-Tarot-API-Key": process.env.TAROT_API_KEY,
  },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

See UnitProofSchema schema reference.

Process proof results

Collection responses contain data, page, per_page, total_pages, and total_count, not a bare array. Process data, then request each subsequent page through total_pages, preserving your filters. Examples show the first page only.

Keep each proof’s id to deduplicate repeated exports and join by job_id/unit_id. Multiple proofs can exist for an item; do not assume a one-to-one relationship or that missing evidence means failure.

For recurring exports, both proof endpoints support created_start and created_end date filters (for example 2026-10-20). Prefer creation dates over event dates to catch delayed uploads, overlap export windows, and deduplicate by proof ID.