> For the complete documentation index, see [llms.txt](https://finext.gitbook.io/one-kyc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://finext.gitbook.io/one-kyc/api/migration-guide.md).

# Migration guide

## What changed

To structurally separate the KYC and KYB products, canonical request paths now carry the `/kyc/` prefix. This makes addressing uniform, isolates access control, and lets each product version independently.

Legacy paths remain backward-compatible and still work. For new integrations, use the canonical paths only.

| Legacy path (deprecated)          | Canonical path                        |
| --------------------------------- | ------------------------------------- |
| `/tenant/v1/applicants/*`         | `/tenant/v1/kyc/applicants/*`         |
| `/tenant/v1/verification-links/*` | `/tenant/v1/kyc/verification-links/*` |
| `/tenant/v1/metrics/*`            | `/tenant/v1/kyc/metrics/*`            |
| `/tenant/v1/audit`                | `/tenant/v1/kyc/audit`                |
| `/tenant/v1/documents/*`          | `/tenant/v1/kyc/documents/*`          |
| `/tenant/v1/media/*`              | `/tenant/v1/kyc/media/*`              |

***

## Migration steps

**Step 1.** Update the base URL in your integration configuration:

```diff
- const BASE_URL = 'https://api.onekyc.io/tenant/v1';
+ const BASE_URL = 'https://api.onekyc.io/tenant/v1/kyc';
```

**Step 2.** Confirm that the API key uses the correct prefix: `kyc_live_*` (production) or `kyc_test_*` (test environment). The canonical `/kyc/*` paths perform additional key-type validation.

**Step 3.** Replace paths in every API call:

```diff
- GET  /tenant/v1/applicants
+ GET  /tenant/v1/kyc/applicants

- GET  /tenant/v1/applicants/{id}
+ GET  /tenant/v1/kyc/applicants/{id}

- GET  /tenant/v1/applicants/external/{external_id}
+ GET  /tenant/v1/kyc/applicants/external/{external_id}

- POST /tenant/v1/verification-links
+ POST /tenant/v1/kyc/verification-links

- GET  /tenant/v1/verification-links/{id}
+ GET  /tenant/v1/kyc/verification-links/{id}

- POST /tenant/v1/verification-links/{id}/revoke
+ POST /tenant/v1/kyc/verification-links/{id}/revoke

- GET  /tenant/v1/documents/{id}
+ GET  /tenant/v1/kyc/documents/{id}

- GET  /tenant/v1/documents/supported
+ GET  /tenant/v1/kyc/documents/supported

- GET  /tenant/v1/media/{media_id}
+ GET  /tenant/v1/kyc/media/{media_id}

- GET  /tenant/v1/metrics/stats
+ GET  /tenant/v1/kyc/metrics/stats

- GET  /tenant/v1/metrics/chart
+ GET  /tenant/v1/kyc/metrics/chart

- GET  /tenant/v1/metrics/funnel
+ GET  /tenant/v1/kyc/metrics/funnel

- GET  /tenant/v1/metrics/activity
+ GET  /tenant/v1/kyc/metrics/activity

- GET  /tenant/v1/metrics/realtime
+ GET  /tenant/v1/kyc/metrics/realtime

- GET  /tenant/v1/metrics/export
+ GET  /tenant/v1/kyc/metrics/export

- GET  /tenant/v1/applicants/{id}/history
+ GET  /tenant/v1/kyc/applicants/{id}/history

- GET  /tenant/v1/applicants/{id}/aml
+ GET  /tenant/v1/kyc/applicants/{id}/aml

- POST /tenant/v1/verification-links/batch
+ POST /tenant/v1/kyc/verification-links/batch

- GET  /tenant/v1/audit
+ GET  /tenant/v1/kyc/audit
```

***

## Backward compatibility

Legacy paths (`/tenant/v1/applicants/`, `/tenant/v1/verification-links/`, etc.) are supported until further notice. The minimum sunset notice is **three months**. The exact date is communicated by email and published in the changelog.

***

## What this means for KYB

The KYB API works **only** through canonical paths: `/tenant/v1/kyb/*`. The split into `/kyc/` and `/kyb/` provides:

* separate API keys for KYC and KYB with independent scopes;
* independent versioning of the two products;
* unambiguous operation identification in audit logs and monitoring systems.

***

## Frequently asked questions

### Do I need to migrate immediately?

No. Existing integrations keep working without changes. Migrate during your next planned update.

### Did the request and response format change?

Yes. Since 21 April 2026, every field in request bodies, response bodies, and webhook payloads uses `snake_case` (for example, `flow_id`, `external_user_id`, `verification_link`). The legacy `camelCase` format (`flowId`, `externalUserId`, `verificationLink`) is still accepted on input and mirrored in responses for compatibility; the sunset date for this transition mode is announced separately. New integrations must use `snake_case` only.

Authentication headers, query parameters, and URL structure (apart from the move to the `/kyc/` and `/kyb/` prefixes) are unchanged.

### How do I verify the migration?

Enable HTTP request logging for OneKYC API calls on your server and confirm that every URL contains the `/kyc/` segment after `/tenant/v1/`.

***

For migration questions, contact technical support: **<info@onekyc.io>**.