Journey Builder API

Use the Journey Builder APIs to run a complete identity verification journey from your backend — start a journey, submit documents and selfies, and finalize verification.

🚧
These APIs are for backend-to-backend integration only. Do not call them from client SDKs. Learn when to use each set of APIs.

Prerequisites

Obtain your API credentials — see API Credentials and Authentication.
Identify your base URL by region:
- EU (Default): https://api.idwise.com/
- UAE: https://api-uae.idwise.com/
- Qatar: https://api-qat.idwise.com/
Have your flow_id ready from the IDWise dashboard.

AI integration prompt

Use this prompt with your AI coding assistant to generate a backend integration for the Journey Builder API. The prompt asks for the required project details first, then generates code for Python, Node.js, or C#.

Copy this prompt into your AI coding assistant to generate a backend-to-backend Journey Builder API integration.

View Integration Prompt

You are an expert backend engineer integrating the IDWise Journey Builder API.

Before writing any code, ask me these questions one at a time:

1. What is your IDWise flow_id?
2. What are your IDWise API key and API secret? If I do not want to paste secrets into chat, ask me for the environment variable names instead.
3. Which backend framework or language are you using: Python, Node.js, or C#?
4. Which IDWise region should the integration use: EU, UAE, or Qatar?
5. Where will the document and selfie image files come from: local file path, uploaded file, object storage, or another source?

After I answer, generate a complete backend integration for the selected language or framework.

The integration must:

1. Use the correct regional base URL:
   - EU: https://api.idwise.com/
   - UAE: https://api-uae.idwise.com/
   - Qatar: https://api-qat.idwise.com/
2. Authenticate with Basic Auth using the API key and API secret.
3. Start a journey with POST /v2/start-journey using flow_id and a unique reference_no.
4. Save the returned journey_id.
5. Parse the start journey response payload to identify all required steps and the step_id for each step in the selected flow.
6. Use only the step IDs returned by the start journey response when calling POST /v2/process-journey-step. Do not hard-code step IDs or use step IDs from a different flow.
7. Add a helper function that prepares the files for each step by reading a mapping table keyed by step_id. The mapping table must use the step_id as the key and values for image and image2, for example: { "<STEP_ID>": { "image": "path-or-file-for-image1", "image2": "path-or-file-for-image2" } }. The developer must review the step IDs returned by the start journey response and fill in this mapping table for the current flow, because step IDs change between flows.
8. Submit each required document or selfie step with POST /v2/process-journey-step using multipart/form-data.
9. Complete the journey with POST /v2/complete-journey after submitting the required steps.
10. Retrieve the final result with GET /v2/get-journey-result.
11. Include success handling, error handling, and clear logging without adding backend polling or retry loops.
12. Keep API credentials out of source code by using environment variables in the final implementation.

Return:

1. A short implementation checklist.
2. Complete runnable code for the selected framework or language.
3. Required environment variables.
4. Example request and response handling.
5. A step-to-file mapping table that the developer must fill in, where each key is a step_id returned by the start journey response and each value contains image and optional image2.
6. Notes explaining how the helper function maps image sources to the step IDs returned by the start journey response.

Do not call these APIs from a client SDK or frontend app. This integration must run only on a trusted backend.

Sequence Diagram

The following diagram illustrates the full backend-to-backend integration flow:

Integration Steps

Start Journey

Create a new verification journey by calling POST /v2/start-journey. This returns a journey_id that you will use in all subsequent calls.

Request:

curl -X POST https://api.idwise.com/v2/start-journey \
  -H "Content-Type: application/json" \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -d '{
    "flow_id": "YOUR_FLOW_ID",
    "reference_no": "applicant-ref-001"
  }'

Parameter	Type	Required	Description
`flow_id`	`string`	Yes	Your verification flow ID from the IDWise dashboard.
`reference_no`	`string`	Yes	A unique reference for this applicant. Alphanumeric and `- _ / \ , . + @` allowed.
`applicant_details`	`object`	No	Applicant info for AML journeys. Requires `full_name`; `birth_date` and `sex` are optional.

Response (200):

{
  "journey_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_no": "applicant-ref-001",
  "is_completed": false,
  "step_summaries": []
}

Save the journey_id — you need it for every following API call.

📘
See the full Start Journey API reference for all parameters and response fields.

Process Journey Step

Submit documents and selfies for each step in the journey by calling POST /v2/process-journey-step. This API processes steps asynchronously — submit an image, then poll Get Journey Summary to confirm processing is complete before moving on.

Repeat this call for each required step (e.g., ID document front, ID document back, selfie).

Request (multipart/form-data):

curl -X POST https://api.idwise.com/v2/process-journey-step \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -F "journey_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -F "step_id=0" \
  -F "image=@/path/to/id-document-front.jpg"

Parameter	Type	Required	Description
`journey_id`	`string`	Yes	The journey ID returned from Step 1.
`step_id`	`integer`	Yes	The step index to process (e.g., `0` for the first step).
`image`	`file`	Yes	The image file for this step (document photo, selfie, etc.).
`image2`	`file`	No	A second image if the step requires it (e.g., back of an ID card).
`is_skipped`	`boolean`	No	Set to `true` to skip this step.

Response (200):

{
  "success": true
}

💡
Processing is asynchronous. Call the Get Journey Summary API to check whether a step has finished before submitting the next step or completing the journey.

See Image Data Requirements for supported image sizes and dimensions. Full parameter details are in the Process Journey Step API reference.

Complete Journey

After all steps are processed, finalize the journey by calling POST /v2/complete-journey. This triggers the final system decision based on all submitted data.

⚠️
Once you call this API, you can no longer submit or modify any steps for this journey.

Request:

curl -X POST https://api.idwise.com/v2/complete-journey \
  -H "Content-Type: application/json" \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -d '{
    "journey_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Parameter	Type	Required	Description
`journey_id`	`string`	Yes	The journey ID returned from Step 1.

Response (200):

{
  "success": true
}

After completion, retrieve the final verification result using the Get Journey Result API. See the Complete Journey API reference for more details.

Full Example

API Reference

API	Description
Start Journey	Create a new identity verification journey.
Process Journey Step	Submit a document or selfie image for a journey step.
Complete Journey	Finalize the journey and trigger the system decision.
Get Journey Summary	Check the current status and step results of a journey.
Get Journey Result	Retrieve the final verification result after completion.