Hosted

The simplest identification method. Create an identification with type Link and receive a URL to pass to your customer for completing verification.

The returned URL is an interface hosted by Iron. Once the customer has completed the flow, Iron reviews the submission, performs verification, and decides on approval. Iron is fully responsible for all compliance obligations, including final verification and ongoing monitoring.

Create a Link Identification

POST /api/customers/{id}/identifications/v2

The request body must include "type": "Link" to select the hosted flow. This is the discriminator that tells the API which identification method to use.

Field	Required	Description
type	Yes	Must be "Link" for hosted identifications
with_edd	No	Set to true to initialize with the full Enhanced Due Diligence process

Bash

curl -X POST "https://api.sandbox.iron.xyz/api/customers/<customer_id>/identifications/v2" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "IDEMPOTENCY-KEY: <unique-request-id>" \
  -H "X-API-Key: <your-api-key>" \
  -d '{ "type": "Link" }'

POST /api/customers/{id}/identifications/v2 accepts an Idempotency-Key header. Retrying with the same key returns the original response. Keys expire after 24 hours. Reusing a key with a different request body returns 409 Conflict.

This endpoint is not an upsert. Every call with a new idempotency key creates a new identification record, and the newest record drives the customer’s status. If you create a new identification while another is in flight, the customer resets to IdentificationRequired and the older identification stops counting, even if it is approved later.

Create one identification, then wait for it to reach a terminal status (Approved, Declined, or Expired) before creating another. To track progress, subscribe to the identification_status webhook or poll GET /api/customers/{id}/identifications. Never re-call this endpoint to refresh status.

Example response:

JSON

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "customer_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "status": "Pending",
  "url": "https://verify.iron.xyz/start?token=...",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z"
}

Pass the url to your customer. They complete the verification flow in the hosted interface, and Iron handles the rest.

Example error:

{
  "error": {
    "code": "customer_not_found",
    "message": "No customer exists with the provided ID.",
    "request_id": "req_7a3b9c2d1e4f"
  }
}

In Sandbox, you can approve or reject the identification via POST /sandbox/identification/{id} instead of waiting for a manual review. See Sandbox.