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.

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.