> ## Documentation Index
> Fetch the complete documentation index at: https://dev.enterprise.moonpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hosted Identification
> Create an identification with type Link and receive a URL to pass to your customer for completing verification. MoonPay Enterprise hosts the flow and handles review.
The returned URL is an interface hosted by MoonPay Enterprise. Once the customer has completed the flow, MoonPay Enterprise reviews the submission, performs verification, and decides on approval. MoonPay Enterprise is fully responsible for all compliance obligations, including final verification and ongoing monitoring.
Present and sign the terms and conditions before creating the identification. Fetch the document via `GET /api/customers/{id}/required-signings` and record acceptance via `POST /api/customers/{id}/signings`. The terms contain the data sharing agreement, so they must be signed before MoonPay Enterprise collects KYC data. Keep this flow reachable afterwards — customers must sign again when a new document is published. See [Terms and Conditions](/onboarding#terms-and-conditions).
## Create a Link Identification
`POST /api/customers/{id}/identifications/v2`
Full request and response schemas live in the [API reference](/reference/customer/create-customer-identification-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 start the full Enhanced Due Diligence process. Individual customers only |
| `Idempotency-Key` (header) | Yes | Unique UUID per request. Requests without it return `400` |
`with_edd` works for Individual customers only. Setting it to `true` on a Business customer returns `400` with the message `"with_edd is not supported for business customers"`.
```bash Bash theme={null}
curl -X POST "https://api.sandbox.iron.xyz/api/customers//identifications/v2" \
-H "Content-Type: application/json; charset=utf-8" \
-H "IDEMPOTENCY-KEY: " \
-H "X-API-Key: " \
-d '{ "type": "Link" }'
```
```typescript TypeScript theme={null}
const response = await fetch(
"https://api.sandbox.iron.xyz/api/customers//identifications/v2",
{
method: "POST",
headers: {
"Content-Type": "application/json; charset=utf-8",
"Idempotency-Key": "",
"X-API-Key": "",
},
body: JSON.stringify({ type: "Link" }),
},
);
const identification = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.sandbox.iron.xyz/api/customers//identifications/v2",
headers={
"Content-Type": "application/json; charset=utf-8",
"Idempotency-Key": "",
"X-API-Key": "",
},
json={"type": "Link"},
)
identification = response.json()
```
`POST /api/customers/{id}/identifications/v2` requires an `Idempotency-Key` header. Requests without one return `400`. Retrying with the same key returns the original response. MoonPay Enterprise caches successful responses only, so a retry after an error executes the request again. Reusing a key with a different request body returns `409 Conflict`.
This endpoint is not a status refresh. If the customer's latest identification is `Pending`, `Processed`, `PendingReview`, or `Approved`, a call without `with_edd: true` returns that existing identification (same `id` and `url`) instead of creating another. A new record is created only when the latest identification is `Declined`, `Expired`, or `Archived`, or the customer has none, and the newest record then drives the customer's status. One exception: if the customer's latest identification is Sumsub-based (every hosted-flow identification is), calling again with `with_edd: true` upgrades that record for EDD instead of creating a new one.
Create one identification, then wait for it to reach a terminal status (`Approved`, `Declined`, `Expired`, or `Archived`) 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 (`201 Created`):**
```json JSON theme={null}
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"customer_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"status": "Pending",
"url": "https://api.sandbox.iron.xyz/verify?",
"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 MoonPay Enterprise handles the rest.
**Example errors:**
Most client errors (`400`, `401`, `403`, `404`, `429`) return a plain JSON string:
```json 404 Not Found theme={null}
"Create customer identification customer not found."
```
A `409` means the `Idempotency-Key` was already used for a request with a different body. It carries no explanatory body, just the status. Send a fresh UUID for each new identification, and reuse a key only when retrying that exact request. See [Idempotency](/idempotency).
The hosted flow does not reject duplicate payloads, so a `409` here never points at an existing identification. That check applies to the `Person` and `Business` flows only. See [KYC/KYB Sharing](/sharing#duplicate-submissions).
Server errors (`500`) return `{ "message": "...", "trace_id": "..." }`. Reference the `trace_id` when reporting issues.
In Sandbox, you can approve or reject the identification via `POST /api/sandbox/identification/{id}` instead of waiting for a manual review. See [Sandbox](/sandbox#update-identification-status).