Platform API

Read-only, cross-account reporting for partners that run file requests on Postal.

The platform API is for partners and internal tooling that need aggregate reporting across accounts: how many submissions a file request received, and which accounts were acquired through it. It is strictly read-only and uses a separate kind of key.

Platform keys are issued by Postal

You cannot create a platform key yourself. Ask your Postal contact. Platform keys always expire, within 1–365 days, and every issue and revocation is audited.

Authentication is the same X-API-Key header. Scopes are platform:read:file-requests and platform:read:accounts. The legacy all wildcard never satisfies a platform scope.

Pagination is page-based: page from 1, pageSize default 50.

File requests

GET /api/v1/platform/file-requests?page=1&pageSize=50&active=true

Scope platform:read:file-requests. pageSize max 100. Sorted by latest submission.

data

{
  "rows": [
    {
      "id": "…",
      "title": "Remix competition",
      "createdAt": "…",
      "active": true,
      "ownerId": "…",
      "ownerName": "Label X",
      "ownerEmail": "ar@labelx.example",
      "freeSubmissions": 412,
      "paidSubmissions": 38,
      "submissionsTotal": 450,
      "latestSubmissionAt": "…"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 3,
  "totalPages": 1
}

Submissions to a file request

GET /api/v1/platform/file-requests/{id}/submissions?page=1&pageSize=50

Scope platform:read:file-requests. pageSize max 200. Newest first.

data

{
  "requestId": "…",
  "active": true,
  "rows": [
    { "kind": "paid", "submittedAt": "…", "itemCount": 3, "submitterId": "sub_9f2c1ab34d5e6f70" }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 450,
  "totalPages": 9
}

submitterId is a keyed hash of the submitter's identity. It is stable, so repeat submitters can be counted across requests, but it cannot be reversed to an email address. It is null when the upload captured no identity.

Accounts

GET /api/v1/platform/accounts?page=1&pageSize=50&createdAfter=2026-08-01

Scope platform:read:accounts. pageSize max 200. Newest first. An invalid createdAfter is ignored.

data

{
  "rows": [
    {
      "id": "…",
      "name": "…",
      "email": "…",
      "username": "…",
      "createdAt": "…",
      "active": true,
      "acquisitionSource": "file_request",
      "acquisitionFileRequestId": "…",
      "acquisitionFileRequestTitle": "Remix competition",
      "acquisitionFileRequestOwnerId": "…"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 1280,
  "totalPages": 26
}

Account holder details are in the clear

Owner and account emails are returned as-is; only submitter identity is hashed. Treat responses as personal data.

File requests

Submissions to a file request

Accounts

On this page