Quickstart
Start an AIS Ident session, open the bank flow and read the identification result.
Before you start
Request credentials enabled for AIS Ident from your IDCanopy contact. Set UMBRELLA_BASE_URL to the sandbox gateway in Environments, and set UMBRELLA_API_KEY and UMBRELLA_CUSTOMER_ID on your backend. You need curl, a browser and a return URL for your application. Do not put API credentials or bearer tokens in browser code.
For a no-credentials walkthrough first, use the clickable demo. It uses test data, not a live bank connection. The commands below describe the documented API integration; they are not evidence of a successful live call.
1. Obtain a bearer token
curl --fail-with-body -X POST "$UMBRELLA_BASE_URL/auth" \
-H "Api-Key: $UMBRELLA_API_KEY" \
-H "Customer-Id: $UMBRELLA_CUSTOMER_ID" \
-H "Content-Type: application/x-www-form-urlencoded"Set ACCESS_TOKEN to the returned access_token in your shell. See Authentication for token expiry.
2. Create an identification session
Use a new referenceId for each session. Replace the illustrative returnUrl with your application URL and the expected name with your test identity.
curl --fail-with-body -X POST "$UMBRELLA_BASE_URL/ais/initiate" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"referenceId": "onboarding-000123",
"returnUrl": "https://app.example.com/ais/return",
"expectedName": { "firstName": "Erika", "lastName": "Mustermann" }
}'Keep the response and your referenceId. The response contains redirectUrl and expiresAt.
3. Complete the hosted bank flow
Open redirectUrl in the browser. Select the bank and complete its login, consent and strong customer authentication. Use the test-bank instructions supplied with your sandbox access. A return to returnUrl can mean success, cancellation or failure; it is not the identification result.
4. Read the result on your backend
curl --fail-with-body -X POST "$UMBRELLA_BASE_URL/ais/status" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"referenceId":"onboarding-000123"}'PENDING: the flow is not final; read status again later.COMPLETED: inspectdecision,nameMatchand the account information. Completion alone is not a positive name match.ABORTED,EXPIREDorFAILED: inspectstatusReasonand handle the unsuccessful session.
A REVIEW decision is not CONFIRMED; a missing bank-holder name can require review. See the decision table.
Next
The AIS Ident integration guide covers the sequence, optional webhook delivery, output modes and errors. The reference defines the request and response fields.