Identification Process

Update : 07/11/2025

Identification Endpoint

Sandbox:

POST https://api.sandbox.billit.be/v1/einvoices/registrations/{RegistrationID}/identification

Production:

POST https://api.billit.be/v1/einvoices/registrations/{RegistrationID}/identification

📝 Precondition

You must have an active registration of your entity, the entity must be created in Billit. When the entity is active, you have a RegistrationID. More info : https://docs.accesspoint.billit.eu/docs/registering-entities. Create it with:

POST https://api.sandbox.billit.be/v1/einvoices/registrations

If you skip or fail this step, calls to /identification will return 404 Not Found or 401 Unauthorized.

🔑 Path Parameters

🔑Header

🛠️ Request Body

{
  "IdentificationProviderTC": "ItsMe",
  "RedirectURL": "https://your.app/after-id-check"
}

⚠️ IMPORTANT

• You have 5 minutes to complete the check from the moment you POST.
• If the session expires or the user abandons, you must re-POST (no resume).
• Remark: when error message appears you are not authorised, contact support Billit and include the partyID of your master account.
• How do you typically launch the process ?
  • From your application
  • With an email notification linking to your application: then the POST command should only be launched when the user clicks on a button/link you provided (keep in mind the 5 minutes)

Example of a Post:

Header of the post (sandbox):

Explanation:

1. POST command contains in Path/URL the RegistrationID of the entity to be verified
2. Header contains partyID = the RegistrationID of the master account (whitelisted for identification)
3. Result is returned in Body

Body of the post:

{
  "IdentificationProviderTC": "ItsMe",
  "redirectURL": "testxyz/redirect"
}

Body of the returned link:

{
    "URL": "https://oidc.prd.itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize?response_type=code&client_id=xWnzcGFNsT&scope=openid+service:BILLITPRD_SHAREDATA+profile+eid+phone+email+address+&state=P2nLhsOjw5zDnXHDnFwifeKAoD9eSVo84oCZ.............44%2bAcOfw7w%3d&prompt=login&max_age=1&redirect_uri=https://my.sandbox.billit.be/API/OAuth2/ItsMe/CallbackAPAAS/"
}

Identification with Itsme on Sandbox versus Itsme on Production

So for testing, you can test on:

• Sandbox :
  • this can be limited to 1 or a few entities for testing the mechanism. No need to run the identication on all the entities
  • Max 5 attempts per entity (sandbox only)
    • Each succeeded or failed attempt is counted as 1
    • If you need to do more testing, continue the testing on another account
    • When exceeding the limit, the error message is : "Code": "TooManyTrials", "Description": "Too many attempts"
• Production
  • Where you could test on your master account, you can run the identification multiple times.

✅ Successful Response (200 OK)

{
  "RedirectURL": "https://idprovider.com/start?session=abc123"
}

Next steps:

1. Issue an HTTP redirect (302) to the returned RedirectURL.
2. Customer (authorised user of the entity) completes the identity flow with the provider (Whitelabeled : no Billit icon or info displayed)
3. Provider redirects back to Billit; Billit will automatically validate internally.

🔄 Final Callback to Your App

After the provider flow, Billit:

1. Validates the incoming request.
2. Determines success or failure.
3. Redirects the user’s browser to your RedirectURL, appending:

?registrationID={RegistrationID}&success=true|false

Example of result:

https://your.app/after-id-check?registrationID=42&success=true

https://your.app/after-id-check?registrationID=42&success=false

https://oidc.prd.itsme.services/clientsecret-oidc/ui/v0.1/oops.html?error=invalid_redirect&error_description=The%20given%20redirect%20uri%20is%20invalid

Note: Always read both registrationID and success query params—without them you won’t know the outcome.

Next action:

• status = success : identification is done, ready to set up integration and/or start sending..
• status = false : identification needs to be relaunched.