Migration guide

What changedCopy Anchor Link

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.

Migration stepsCopy Anchor Link

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

- const BASE_URL = 'https://api.knowakyc.com/tenant/v1';
+ const BASE_URL = 'https://api.knowakyc.com/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:

- 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 compatibilityCopy Anchor Link

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 KYBCopy Anchor Link

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 questionsCopy Anchor Link

Do I need to migrate immediately?Copy Anchor Link

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

Did the request and response format change?Copy Anchor Link

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?Copy Anchor Link

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

For migration questions, contact technical support: legal@knowakyc.com.