Payee Check API

Request

POST /api/v1/payee-check

curl -X POST https://thepersonagrata.com/api/v1/payee-check \
  -H "Authorization: Bearer pgc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "claimed_pg_id": "PG-7F3A9C",
    "claimed_name": "Maya Laurent",
    "payee": { "name": "Northlight Talent", "email": null, "iban_holder_name": null, "handle": null }
  }'

const res = await fetch('https://thepersonagrata.com/api/v1/payee-check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    claimed_pg_id: 'PG-7F3A9C',
    claimed_name: 'Maya Laurent',
    payee: { name: 'Northlight Talent', email: null, iban_holder_name: null, handle: null },
  }),
})
const check = await res.json()
if (check.result !== 'verified_representative') {
  showWarning(check) // ask your customer to confirm before paying
}

Response

{
  "check_id": "PAY-8K2M4Q7Z",
  "result": "verified_representative",
  "pg_id": "PG-7F3A9C",
  "representative": {
    "type": "agency",
    "name": "Northlight Talent",
    "mandate_scopes": ["negotiate_licenses", "create_proofs"]
  },
  "checked_at": "2026-10-27T10:15:00Z"
}

• verified_representativeThe payee is the person themselves, or an agency with an active mandate that includes negotiate_licenses.
• not_a_representativeThe person is a verified member, but the payee matches nobody who represents them.
• unknownThe person is not a Persona Grata member. Treat as unverified, not as safe.

Errors and limits

• 400 invalid_requestMissing payee.name, or neither claimed_pg_id nor claimed_name is set.
• 401 unauthorizedMissing or revoked API key.
• 429 rate_limitedToo many requests. Retry after the time in the Retry-After header.
• 500 server_errorSomething went wrong on our side. Retry with backoff.

The same per-key rate limit as the Clearance API applies.

Typical integration

Show a warning to your customer before they confirm a payment to someone claiming to represent a public figure. Call the endpoint when the payee is entered, and if the result is not verified_representative, show a clear warning with the options to cancel or continue. Never block silently, and never treat unknown as safe.