v1

latestOpenAPI 3.1.02026-07-13143194365.4 KB
claim

Look up a reserved account by handle

Look up a pre-registered (reserved) account by handle and return the set of verification methods available to claim it. Lets a prospective claimer confirm "this account is mine" and pick how they want to prove ownership.

This endpoint is unauthenticated. To avoid enumeration, the response is identical for all miss reasons:

  • Handle does not exist
  • Handle resolves to an organic account (never reserved)
  • Handle resolves to a reserved account that has already been claimed

In all of those cases, the response is {"is_claimable": false, ...} with all other fields null/empty. Only handles that resolve to unclaimed pre-registered accounts produce a positive response.

The endpoint is rate-limited per client IP. Both hit and miss branches execute the same DB query pattern so response timing does not leak account state.

The claim_options list contains one entry per verifiable identity attached to the account. The frontend renders one button per option and dispatches on method to pick the right verification flow:

  • method="otp" — email or SMS OTP. display is masked (e.g. a***@gmail.com) since the underlying identity is PII.
  • method="oauth_*" — OAuth flow for the named platform. display is the raw social handle/URL since social platforms are public by definition.

Only OAuth providers with working verification today are included (see LinkedIdentityType.OAUTH_CLAIMABLE). New platforms must be added to that inclusion list explicitly once their verify endpoint ships.

Error codes:

  • 422: Missing or malformed handle parameter
  • 429: Rate limit exceeded for this client IP
get/v1/account/claim/lookup

Query parameters

handlestring required

Handle to look up (case-insensitive)

Example:alice

Handle to look up (case-insensitive)

Response

Successful Response

is_claimableboolean required

True if the handle resolves to a pre-registered account that has not yet been claimed

handlestring nullable

The normalized handle. Only set when is_claimable=true.

pre_registered_atstring nullable

ISO timestamp of when the account was reserved. Only set when is_claimable=true.

Example response

{
  "claim_options": [
    {
      "type": "email",
      "display": "a***@gmail.com",
      "method": "otp"
    }
  ]
}