> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iron.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

<CodeGroup>
  ```bash Bash theme={null}
  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" }'
  ```
</CodeGroup>

<Note>
  `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`.
</Note>

<Warning>
  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.
</Warning>

**Example response:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

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

**Example error:**

```json theme={null}
{
  "error": {
    "code": "customer_not_found",
    "message": "No customer exists with the provided ID.",
    "request_id": "req_7a3b9c2d1e4f"
  }
}
```

<Note>
  In Sandbox, you can approve or reject the identification via `POST /sandbox/identification/{id}` instead of waiting for a manual review. See [Sandbox](/sandbox#update-identification-status).
</Note>