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

# Hosted verification links

> Mint a Venly-hosted KYC or KYB link, hand it to the end-user, and collect the verdict.

The default verification route. Venly hosts the onboarding page, so you never handle identity
documents — you mint a URL, hand it over, and wait.

Works for both party types: the KYC flow for an `INDIVIDUAL`, the KYB flow for an `ORGANISATION`.

<Steps>
  <Step title="Create the party">
    Create an [`INDIVIDUAL` or `ORGANISATION` party](/api-reference/Finance-API/parties/create-a-new-party).
    It starts unverified.
  </Step>

  <Step title="Mint a link">
    [`POST /parties/{partyId}/verification`](/api-reference/Finance-API/parties/create-a-verification-link)
    with **no request body** — the party's stored `partyType` decides the flow.

    ```bash theme={null}
    curl -X POST https://api.venlyfinance.com/v1/parties/{partyId}/verification \
      -H "Authorization: Bearer {access_token}"
    ```

    ```json theme={null}
    {
      "success": true,
      "result": {
        "partyId": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22",
        "verificationUrl": "https://onboard.venly.io/kyc?token=inv-tok-9f2c41ab",
        "status": "VERIFICATION_PENDING"
      }
    }
    ```

    Only the URL for the party's own flow is returned — there's no choice to make and no second URL.
  </Step>

  <Step title="Hand the URL to the end-user">
    Redirect them, or deliver it over a channel you trust.

    <Warning>Treat `verificationUrl` as a credential. It grants access to that user's onboarding session — don't log it, don't put it anywhere shared, and don't email it to a group address.</Warning>
  </Step>

  <Step title="Collect the verdict">
    The verdict arrives asynchronously. [Register a webhook](/guides/finance/webhooks), or poll
    [Get a party](/api-reference/Finance-API/parties/get-party-details) and read `kycStatus`
    (individuals) or `kybStatus` (organisations).
  </Step>
</Steps>

## Links do not expire

Worth internalising, because it simplifies your error handling more than you'd expect:

| You call it again…                         | You get                                                              |
| ------------------------------------------ | -------------------------------------------------------------------- |
| While the link is still live               | `200` with the **same** `verificationUrl`. No new session is minted. |
| After the link was revoked on Venly's side | `201` with a **freshly minted** URL.                                 |
| When the party is already `VERIFIED`       | `409 party-already-verified`.                                        |

So **"re-send the verification link" is a safe, idempotent operation.** You don't need to store the
URL, track link state, or worry about handing a user a dead link by calling twice. If a user says they
lost the email, just call it again.

The distinction between `200` and `201` is informational — both carry a usable URL in the same shape.
Treat any `2xx` as success rather than branching on the code.

## The `status` field

The response's `status` is the party's verification status **at mint time**, which tells you what state
the party was in when you asked:

| Party type     | Possible values                    |
| -------------- | ---------------------------------- |
| `INDIVIDUAL`   | `VERIFICATION_PENDING`, `REJECTED` |
| `ORGANISATION` | `PENDING`, `DENIED`                |

It is never `VERIFIED` — an already-verified party returns `409` instead of a link. Seeing `REJECTED`
or `DENIED` here means you're re-verifying someone who previously failed, which is allowed.

## Errors

| Status | Code                                | Retryable | What to do                                                                                                        |
| ------ | ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `409`  | `verification-not-provisioned`      | No        | Your company has no provisioned verification tenant. Contact Venly — configuration, not something retrying fixes. |
| `409`  | `party-already-verified`            | No        | Nothing to do; the party is done.                                                                                 |
| `404`  | —                                   | No        | No such party for your company.                                                                                   |
| `500`  | `identity-verification-rejected`    | No        | The platform rejected the request itself. Contact support.                                                        |
| `503`  | `identity-verification-unavailable` | **Yes**   | Platform unreachable. Retry with backoff.                                                                         |

Full list in [Troubleshooting](/guides/finance/onboarding/troubleshooting).

## When to use this route

<CardGroup cols={2}>
  <Card title="Use hosted links when" icon="circle-check">
    You have no existing KYC provider · you're verifying an organisation · your company runs
    Venly-managed wallets · you'd rather not touch identity documents at all
  </Card>

  <Card title="Consider the alternative when" icon="forward" href="/guides/finance/onboarding/sumsub-token-sharing">
    You already verified this **individual** in your own Sumsub account **and** run `SELF_CUSTODY` —
    then token sharing avoids a second flow
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Sumsub token sharing" icon="forward" href="/guides/finance/onboarding/sumsub-token-sharing">
    The alternative route for individuals.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/finance/onboarding/troubleshooting">
    Tracking linkage and resolving failures.
  </Card>
</CardGroup>