Tells you when an ID you hold is no longer an ordinary active person: suspended, revoked, deleted, merged into another, or rotated. Call it regularly with the IDs you have.
Request
http
POST /v1/subjects/status
Host: id.humanpass.co
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
{ "subs": ["1.Ab3x…", "1.Q9zK…"] }- Authenticate with your client's ID and secret (HTTP Basic). Public clients, which have no secret, can't call it: use a server-side client of the same project.
- Up to 500 IDs per request, each up to 64 characters.
- It answers only about IDs in your client's own project.
Response
json
{
"results": [
{ "sub": "1.Ab3x…", "status": "active" },
{ "sub": "1.Q9zK…", "status": "merged", "replaced_by": "1.Lm4p…" }
]
}| status | replaced_by | What to do |
|---|---|---|
active | Nothing. | |
suspended | Suspend the account; it may come back. | |
revoked | Close or restrict the account. | |
deleted | Treat as deleted. | |
merged | yes | Combine with the account under replaced_by, or move to it. |
rotated | yes | Move the account to replaced_by: same person. |
Errors
| HTTP | error | Why |
|---|---|---|
| 401 | invalid_client | Wrong or missing client credentials. |
| 400 | invalid_request | subs missing, empty, more than 500, or not strings of up to 64 characters. |
How often
Daily is plenty for most sites. Check every ID you hold, in batches of 500, not just people who signed in recently: the point is to hear about people who don't come back. The dashboard shows each client's last check.