Your first Vouched API request

Start with the right access

The Read API retrieves one brand's records. It is separate from signing in to Vouched and does not let an integration approve creative, fund a campaign or release money.

You need Brand Plus or above, an owner-level brand account and a verified brand to create a key. Open Developers in your brand dashboard. If access is unavailable, ask the primary owner or contact Vouched. Do not share somebody else's personal login.

1. In Developers, give the API key a name that identifies the integration.
2. Select Create and copy the key once into a secret manager or a server-side environment variable.
3. Keep the key out of browser code, public widgets, repositories, screenshots and support messages.

Read your campaigns

Set VOUCHED_ORIGIN to the origin shown on your Developers page, with no trailing slash. Set VOUCHED_KEY securely to the key you just created. Run this from your own terminal or backend, not a public browser embed.

curl --fail-with-body "$VOUCHED_ORIGIN/api/v1/campaigns?limit=50" \
  -H "Authorization: Bearer $VOUCHED_KEY"

1. A successful response contains resource, count and data.
2. An empty data array is a valid result when there are no matching records.
3. The key chooses the brand. There is no brand_id parameter for switching into another brand's records.

What you can read

The HTTP Read API exposes six resources: campaigns, submissions, payouts, deposits, conversions and links. Replace campaigns in the example URL with the resource you need.

Use limit for a bounded result, default 50 and maximum 200. Page with cursor: a full page returns next_cursor, and sending it back reads the page after it. A page shorter than the limit is the last one and carries no cursor.

Results are newest first. The older since parameter still works and is superseded by cursor: it filters on a timestamp alone, so rows sharing a timestamp with the last row of a page are skipped. Neither parameter is an update feed: a later status change to an older record does not resurface it. Walk the cursor to read everything once, and use Records for summaries.

Recover without guessing

401 missing_key: send the Authorization header with the exact Bearer prefix. 401 invalid_key: confirm the key belongs to the intended environment and has not been revoked.

404 unknown_resource: use one of the six documented resource names. 429 rate_limited: back off; all keys and API/MCP calls share one brand limit: Plus 60, Pro 120, Enterprise 240 requests per minute. Do not retry continuously.

For a 500 response, check parameter formats and contact support if it persists. Share the route, time and status, never the key or private response data.

The machine-readable version

The OpenAPI description lives at /openapi/vouched.yaml on this origin. Point an API client or a code generator at it rather than transcribing the fields by hand.

The reference pages behind it are in the repository under docs/api: authentication, pagination, errors, webhooks, and one page per resource with its exact fields. A guard test fails if a resource the API serves is missing from either of them.

Replace a key safely

Create a replacement key, update your integration, verify it can read the intended brand and then revoke the old key. Revoked keys can no longer read records. If a key is exposed, revoke it immediately and issue a replacement.

This guide covers the Read API only. Conversion ingestion and independent measurement endpoints have separate contracts and are not interchangeable with these six read resources.

Common questions