API Reference

The AdPriva API lets developers fetch, verify and export cryptographic proofs of engagement.

All requests require authentication with your API key (available in the Developer Dashboard).

Base URL

https://api.adpriva.com/v1

Authentication

Include your API key in the header:

Authorization: Bearer YOUR_API_KEY

Example with curl:

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.adpriva.com/v1/proofs

Endpoints

1. List Proofs

Retrieve proofs (Consent Receipts, Bounded-Use Proofs, Engagement Proofs).

Request

GET /proofs?siteId=acme-blog&type=click

Response

[
  {
    "proof_id": "PRF_12345",
    "type": "click",
    "site_id": "acme-blog",
    "publisher_id": "PUB_67890",
    "timestamp": "2025-09-25T12:34:56Z",
    "valid": true
  }
]

2. Verify a Proof

Check if a specific proof is valid.

Request

GET /verify/PRF_12345

Response

{
  "proof_id": "PRF_12345",
  "valid": true,
  "zk_verified": true,
  "anchor_ref": "https://explorer.adpriva.com/PRF_12345"
}

3. Get Snapshots

Fetch tamper-evident Merkle-root snapshots for audits.

Request

GET /snapshots/2025-09-24

Response

{
  "date": "2025-09-24",
  "merkle_root": "0xabc123...",
  "anchor_tx": "0xdef456...",
  "explorer_url": "https://explorer.adpriva.com/snapshots/2025-09-24"
}

4. Export Portable Verification Certificate (PVC)

Generate a compliance-ready certificate for a site or engagement batch (PDF or JSON).

Request

POST /certificates/export
Content-Type: application/json

{
  "siteId": "acme-blog",
  "format": "pdf"
}

Response

{
  "certificate_id": "PVC_99999",
  "format": "pdf",
  "url": "https://cdn.adpriva.com/certificates/PVC_99999.pdf"
}

5. Server-to-Server (S2S) Event Validation

Validate post-click server-side events (signups, installs, custom events).

Request

POST /conversions
Content-Type: application/json

{
  "click_proof_id": "PRF_12345",
  "event": "signup",
  "timestamp": "2025-09-25T14:12:00Z",
  "signature": "hmac_sha256_signature"
}

Response

{
  "conversion_id": "CNV_55555",
  "status": "verified",
  "proof_id": "PRF_12345"
}

Notes

• Rate Limits → 100 requests/sec per API key
• Error Handling → errors return JSON with code + message (e.g. 401, 404, 500)
• SDKs → official SDKs in JavaScript, Python, Go (see Developer Docs)
• Sandbox/Testnet → use https://sandbox.api.adpriva.com/v1 for safe testing

With the AdPriva API, every engagement can be fetched, verified and certified, bringing cryptographic trust to your validation workflows.

{% @mermaid/diagram content="sequenceDiagram
participant D as Developer Client
participant A as AdPriva API
participant P as Proof Engine
participant X as AdPriva Explorer
participant R as Response

D->>A: HTTPS Request (with API Key)
A->>P: Validate & Process Proof Request
P-->>A: Proof Status / Snapshot / Certificate
A->>X: (Optional) Log or Fetch Anchored Proof
A-->>D: JSON Response
D->>R: Display results in dashboard or app" %}