IDCanopy Developers
IDCanopy APIKYCAIS Ident

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: inspect decision, nameMatch and the account information. Completion alone is not a positive name match.
  • ABORTED, EXPIRED or FAILED: inspect statusReason and 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.

On this page