PII Recovery API

PII Recovery API lets an advertiser retrieve the decrypted personal information (name, email, phone, address, date of birth, city) for a specific lead they received through MAO — on demand, without ever receiving that PII in plaintext through the original ad response.

This is the advertiser-facing half of PII Encryption: publishers encrypt PII in transit, and advertisers recover it here when they need it.

Requirement — capture your PiiRefToken

Before you can call this endpoint, your campaign’s Dynamic URL (or Title/Description) must include the [PiiRefToken] macro, the same way you may already use macros like [SourceID]. MAO substitutes it with a real, single-use token at ad-serving time — that token is what you pass to this endpoint later, per lead.

Caution

[PiiRefToken] only resolves to a real value when the visitor actually submitted PII that a publisher encrypted for that event. Otherwise the macro resolves to an empty string.

GET https://api.myadoptimizer.com/api/MAOPiiRecovery

Response format: JSON

Note

Both GET and POST are accepted; either way, AdToken and PiiRefToken are read from the query string.

Query String Parameters

Parameter	Type	Description	Requirement
AdToken	string (GUID)	Your advertiser token. Request it from your account manager.	Required
PiiRefToken	string	The token captured from the [PiiRefToken] macro for the specific ad event you want to recover PII for.	Required

Example response

{
  "FName": "Jane",
  "LName": "Doe",
  "Email": "jane.doe@example.com",
  "Phone": "+11234567890",
  "Address": "123 Main St",
  "DOB": "1990-01-01",
  "City": "Springfield"
}

Caution

The response is never cached (Cache-Control: no-store) — every call re-reads and re-decrypts from source. Don’t build your own caching layer on top of it; each PiiRefToken is meant to be redeemed as needed, not polled.

Response status codes

Status	Meaning
200	PII recovered successfully.
400	AdToken or PiiRefToken missing, or AdToken isn’t a valid GUID.
401	AdToken doesn’t match an active advertiser account.
403	PiiRefToken is valid but belongs to a different advertiser’s campaign.
404	PiiRefToken not recognized.
410	PiiRefToken has expired — recovery windows are open for 30 days after the ad event.
429	Too many failed lookups (404/403/410) for your account in a short window. Wait a few minutes and retry.
500	Internal error — retry; contact your account manager if it persists.

Note

Every call — successful or not — is written to an audit log with a timestamp and result. Repeated 404/403/410 results from the same account are treated as a possible token-enumeration attempt and will temporarily block further requests (429) from that account.