post
https://api.idwise.com/journey/v2/trigger-kyc-renewal/
Asks the end user to renew their KYC by resubmitting one or more steps of a completed journey.
Usage
Use this API to ask an end user to renew their know your customer (KYC) information by resubmitting steps of a completed journey. For example, you can request a document or selfie. You choose the steps and how many days the user has to complete the renewal.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
journey_id | string | Yes | The ID of the journey to renew. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
step_ids | array of integers | Yes | The IDs of the steps the user must resubmit. |
renewal_window_days | integer | Yes | How many days the user has to complete the renewal, from 1 to 60. The deadline is the end of the last day. |
Base URL by Region
Use the base URL for the region where your services are hosted. The API uses the EU region URL by default.
- EU (Default): https://api.idwise.com/
- UAE: https://api-uae.idwise.com/
- Qatar: https://api-qat.idwise.com/
Authentication
Follow API Credentials and Authentication to authenticate your request.
Error Responses
All errors use this format:
{
"success": false,
"message": "Step 3 is not part of the journey.",
"request_id": "..."
}| HTTP Code | When |
|---|---|
| 400 | renewal_window_days is missing, is not a whole number, or is outside 1–60. |
| 400 | step_ids is missing or empty. |
| 400 | A step ID is not part of the journey, is a document back side, or was not completed (or was skipped). |
| 400 | The journey is not completed |
| 400 | One or more of the steps are already waiting for resubmission. |
| 401 | The API credentials are missing or invalid. |
| 403 | The API credentials do not have the Trigger KYC Renewal permission, or cannot access this journey. |
| 404 | The journey was not found. |
| 409 | The journey is being processed. Retry the request after a short delay. |
What Happens After the Request
- The request puts the selected steps in a waiting-for-resubmission state. The user can resubmit them in the same journey through the software development kit (SDK) or the web flow.
- You do not receive a re-KYC webhook when the renewal starts, because your system requested it. A webhook is a notification sent to your system.
- Your request replaces any scheduled renewals for the same steps, such as a document expiry reminder.
- If the user does not resubmit before the deadline, you receive the ReKyc Deadline Exceeded webhook, as with scheduled renewals.
- Once the user resubmits, the system processes the journey again. You receive the usual journey webhooks with the new result.
- You can see the renewal in the journey timeline in the IDWise dashboard as KYC renewal requested manually.
Note: The API rejects a request to renew a step that is already waiting for resubmission. Wait until the user resubmits it or its deadline passes before you request a new renewal for that step.