Run PII expansion

POST/v1/pii-expansion

Requires X-API-Key or Authorization: Bearer with a provisioned API key.

Create a PII-expansion job and wait for an inline result when responseMode is sync. If the job does not finish before the inline timeout, or when responseMode is async, the API returns a persisted job envelope. Every response includes X-Job-Id for later lookup.

Request body

Field	Type	Required	Description
`depth`	`ExpansionDepth`	No	Default: `"standard"`
`maxCandidates`	integer	No	Maxcandidates Default: `10`
`responseMode`	`ResponseMode`	No	Default: `"sync"`
`seeds`	`PiiExpansionSeeds`	No	—
`subject`	`PiiExpansionSubject`	Yes	—

Request examples

Seeded identity expansion

Expand from one or more supported email, phone, or username seeds.

{
  "depth": "standard",
  "maxCandidates": 10,
  "responseMode": "sync",
  "seeds": {
    "emails": [
      "[email protected]"
    ],
    "phones": [
      "+15555550100"
    ],
    "usernames": [
      "johnsmith"
    ]
  },
  "subject": {
    "name": "John Smith"
  }
}

Responses

`200`

Normalized identity and related social-candidate results when completed inline, otherwise a job envelope.

Schema: PiiExpansionResult or JobEnvelope_PiiExpansionResult_

`422`

Validation Error

Field	Type	Required	Description
`detail`	array<`ValidationError`>	No	Detail

OpenAPI

Download the full OpenAPI contract from /openapi.yaml.