Skip to main content

Evidence exports

An export gives your compliance team a file of acceptance records for a period, for an audit, a dispute or a regulator. You create an export with a filter, Propper freezes the matching records at that moment, and you download the result as a CSV or JSONL file, with optional evidence parts whose signed receipts you can verify.

Every call needs a click:export token. The scope is standalone: click:admin, click:write and click:read do not include it, so request it explicitly (see OAuth scopes). A user token carries it only when the user's role can export evidence.

ResourcePurpose
POST /v1/click/exportsCreate an export.
GET /v1/click/exportsList your organization's exports, newest first.
GET /v1/click/exports/{id}Read an export's status, counts and file list.
GET /v1/click/exports/{id}/files/{name}Download one file.
DELETE /v1/click/exports/{id}Delete an export. Its files then answer 410.

The base path is https://api.propper.ai/v1/click/exports.

Create an export​

curl -X POST https://api.propper.ai/v1/click/exports \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: 5b0f6c1e-0d2a-4c53-9e0f-3f6c2a7d1b10" \
-d '{
"format": "csv",
"filters": {
"from": "2026-01-01T00:00:00Z",
"to": "2026-10-01T00:00:00Z",
"environment": "PRODUCTION",
"outcome": "ACCEPTED"
}
}'
FieldDescription
formatRequired. csv or jsonl.
filters.from, toRequired, inclusive, at most 366 days apart.
filters.templateIdOnly acceptances of this template.
filters.versionIdOnly acceptances of this template version. With templateId, the version must belong to that template.
filters.environmentPRODUCTION or SANDBOX.
filters.outcomeACCEPTED, DECLINED or EXPIRED.
filters.signerRefOnly acceptances by this signer, an exact match on the reference you sent when recording them.
restrictedAccessOptional { "reason", "claimRef" }. Includes records under a legal restriction. See below.
includeEvidenceOptional, default false. true adds evidence parts for records with signed receipts. See below.

The filter list is closed. An unknown key, including q, is a 400 CLICK_VALIDATION_FAILED.

Send signerRef in the body

A signerRef filter goes in the POST body and nowhere else. A query string reaches load-balancer and proxy logs, so a signer reference there would be written to logs outside Propper's control. The export is frozen to the matching acceptances when it is created and the reference is then discarded: the export stores only that a signer filter was used, and never returns the value.

Restricted records​

Without restrictedAccess, records under a legal restriction are left out, and counts.restrictedExcluded says how many. To include them, send a reason (DISPUTE_DEFENSE, DISPUTE_ESTABLISH, COURT_ORDER or REGULATOR_REQUEST) and a claimRef, an identifier for the matter of 1 to 128 letters, digits and . _ : / -, starting with a letter or digit. Free text in either field is a 400. Both are recorded in the audit log.

The response​

The API answers 202 Accepted with a Location: /v1/click/exports/{id} header and the job:

{
"data": {
"id": "0d3b6f0a-5f2e-4a5c-9a38-2c1e7b4d9f10",
"status": "READY",
"format": "csv",
"includeEvidence": true,
"filters": {
"from": "2026-01-01T00:00:00Z",
"to": "2026-10-01T00:00:00Z",
"environment": "PRODUCTION",
"outcome": "ACCEPTED"
},
"asOf": "2026-10-29T17:02:11Z",
"rowCount": 1240,
"counts": { "accepted": 1240, "declined": 0, "expired": 0, "restrictedExcluded": 0 },
"files": [
{ "name": "rows.csv", "contentType": "text/csv", "rows": 1240 },
{ "name": "evidence-0001.zip", "contentType": "application/zip", "rows": 200 },
{ "name": "evidence-0002.zip", "contentType": "application/zip", "rows": 40 }
],
"createdAt": "2026-10-29T17:02:11Z",
"expiresAt": "2026-11-05T17:02:11Z"
}
}

asOf is the moment the records were frozen: acceptances recorded later are not in the export. Send an X-Idempotency-Key so a retry after a timeout returns the same export instead of creating a second one. The key is scoped to your client and the request body, so it cannot replay another client's export.

Status values​

StatusMeaning
PENDINGAccepted, not started.
PROCESSINGBeing prepared.
READYFiles can be downloaded.
FAILEDCould not be prepared. Create a new export.
EXPIREDPast expiresAt. Files answer 410.
DELETEDDeleted with DELETE. Files answer 410.
VOIDEDWithdrawn because a signer it covers was erased. Files answer 410.

An export is usually READY in the create response. Poll GET /v1/click/exports/{id} until status is READY anyway, so your integration keeps working if preparation becomes asynchronous.

Download a file​

curl -OJ https://api.propper.ai/v1/click/exports/0d3b6f0a-5f2e-4a5c-9a38-2c1e7b4d9f10/files/rows.csv \
-H "Authorization: Bearer $TOKEN"

files in the job lists the file names to ask for. The body is streamed, never a link, so your token is checked on every download. The response carries:

HeaderValue
Content-Typetext/csv; charset=utf-8, application/x-ndjson; charset=utf-8 or application/zip
Content-Dispositionattachment; filename="click-export-<id>-rows.csv" (.jsonl for JSONL, the part name for ZIP)
X-Export-RowsThe number of records in the file, frozen at create time.
Cache-Controlprivate, no-store

Check the download is whole before you rely on it:

  • A failure after the first byte closes the connection instead of ending the body cleanly, so a short or broken download is always an error in your HTTP client, never a file that looks complete.
  • A JSONL file ends with a line {"type":"end","rows":N}. Count the record lines and compare with N and X-Export-Rows.
  • A CSV file has one header line followed by X-Export-Rows records.
  • An evidence part is a ZIP file: check that it opens, and that its last entry is manifest.json.

Row columns​

CSV columns and JSONL keys are the same, in this order.

ColumnContents
acceptanceId, receiptIdThe acceptance and its receipt.
outcome, acceptedAt, startedAtWhat the signer did and when.
templateId, templateName, versionId, version, versionLabel, revisionId, revisionNumber, deploymentId, environmentThe agreement that was served.
locale, consentMethod, evidenceTier, deviceClassHow the acceptance was made.
signerRefThe signer reference you sent. erased: followed by 16 hex characters after an erasure.
emailEmpty for acceptances recorded before email was captured. Pseudonymized after an erasure.
ipAddressThe signer's address. 0.0.0.0 after an erasure.
identityErasedtrue once the signer's identity was erased.
restrictedtrue for a record under a legal restriction (only present when you asked for those).
formatVersion, servedChecksum, resolvedSettingsHash, chainSequence, previousChainHash, chainHash, signatureAlgorithm, signatureKeyId, signatureThe tamper-evident chain and signature of the evidence bundle.
evidenceStatusState of the evidence bundle when the export was created.
evidenceFilesnot_exported_v1 for a record made before signed receipts held commitments. For others, always pending: the record's files are in the evidence parts, and evidenceStatus says whether its evidence was processed when the export was created.
screenshotsealed for acceptances with signed receipts that hold commitments: the screenshot is never included in an export. Empty for older records.
consentChoicesThe choices the signer made, as a list.

The export never contains the raw user agent, merge data, captured page HTML or debug logs. A CSV cell that starts with =, +, -, @, a tab or a carriage return is prefixed so a spreadsheet does not run it as a formula. JSONL values are not altered.

Delete an export​

DELETE /v1/click/exports/{id} answers 204. It clears the stored filters at once, and every file of the export then answers 410 CLICK_EXPORT_GONE. Exports are deleted for you 7 days after they were created.

Errors​

Errors use the standard body.

StatuserrorCodeWhen
400CLICK_VALIDATION_FAILEDAn unknown or invalid filter, q, a window over 366 days, or free text in restrictedAccess.
401No or invalid token.
403The token does not carry click:export.
404CLICK_NOT_FOUNDThe export, template or version is not your organization's, or the file name is not one of files.
409CLICK_EXPORT_NOT_READYA file was requested before the export was READY.
410CLICK_EXPORT_GONEThe export expired, was deleted or was voided.
422CLICK_EXPORT_TOO_LARGEThe filter matches more rows than one export allows, or more records than one export may carry evidence for. Narrow the window or add a filter.
429CLICK_EXPORT_LIMIT_REACHEDA concurrency, daily or per-file limit was reached. Wait for Retry-After seconds.

See Limits and retries for the values.

Evidence parts​

With includeEvidence: true, the export also lists evidence parts, evidence-0001.zip, evidence-0002.zip and so on, in files. Each part holds at most a set number of records and bytes (Limits and retries lists them), and rows in files is the number of records in that part. Parts carry only records whose signed receipt holds commitments rather than plaintext identity (format 2). A record from before that format is in the rows file only, and says evidenceFiles: not_exported_v1.

What a part contains​

EntryContents
keys.jsonThe public signing keys the part's receipts name: key id, fingerprint, public key, and status (trusted, revoked with a reason, or unlisted).
content/<versionId>-<locale>.htmlThe text the signer was shown for that version and language, read from your organization's own record of it.
<acceptanceId>/receipt.jsonThe signed receipt.
<acceptanceId>/certificate.pdfThe certificate of the acceptance.
<acceptanceId>/verification.jsonThe result of Propper's own check of the record at the time of download: the verdict and each check.
manifest.jsonWritten last. Every entry above with its sha256 and size, each record with its status, and a missing list.

manifest.json is the last entry, so a ZIP that ends without it was cut short. Its missing list names every file that could not be included and why, for example a certificate that was never produced, so an absent file is always accounted for. A record's status is included, incomplete (something is in missing) or pending. A pending record is one whose evidence had not finished processing when the export was created: it has no files, in every download of the part, even after the evidence is ready. Create a new export to include it.

A screenshot and the captured page are never part of an export. An acceptance whose signer was erased appears with its pseudonym only.

Download the same part twice and you get the same bytes, so a part that failed can be fetched again and compared. Each download counts toward the per-file download limit.

Verify a part​

keys.json carries the public key of each receipt's signing key, and lists a revoked key with its status and reason. It travels with the part, so on its own it proves nothing about whether a key is Propper's: anyone could write such a file. Confirm that once, with Propper, and the rest needs no network.

  1. Check each entry's sha256 against manifest.json.

  2. Pick one receipt from the part and send its JSON as the body of POST /v1/click/evidence/verify/json with a click:read token:

    curl -X POST https://api.propper.ai/v1/click/evidence/verify/json \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @<acceptanceId>/receipt.json

    valid: true with a passing signature and keyValidity check means Propper recognises the receipt's signing key and the signature holds. The check looks nothing up in your account: it needs only signature and signatureKeyId in the receipt.

  3. Compare that receipt's signatureKeyId with the entry in keys.json. A key with status revoked or unlisted does not verify.

  4. For every other receipt signed by the same key, verify the Ed25519 signature over the receipt, with the signature, signatureKeyId and signatureAlgorithm fields removed, using the public key in keys.json. No call to Propper is needed.

  5. Check that the sha256 of content/<versionId>-<locale>.html equals the servedChecksum the receipt binds.

verification.json is Propper's check at download time, for convenience: the steps above do not depend on it.