InstantAuthority
Our InstantAuthority product is a combination of an authorisation lookup towards the Dutch Chamber of Commerce (KvK, from Dutch "Kamer van Koophandel") and the Dutch ID method iDIN.
The service validates that the personal information from iDIN matches the records provided by KvK for a given organisation. By combining the two services, we ensure that the person accessing the service has authority within the provided organisation.
The flow explained
- The merchant initiates the API by sending a request that includes the organisation's KvK number and the required authentication parameters.
- The merchant redirects the end-user to the identity proofing URL provided in the response of the API.
- The end-user authenticates with iDIN and consents to sharing their identity attributes.
- The data obtained in steps 1 and 3 is sent to the KvK service, which checks for the "best matching" role that exists in the target organisation.
- The service returns an API response with the following information:
- The identity attributes of the end-user (as retrieved via iDIN).
- The organisational data of the organisation as registered in the KvK.
- Match results, including the person's name, date of birth, role, mandate and optional mandate limitations
- All other functionaries that have authorisation within the organisation
Getting started
To gain access to test InstantAuthority, you can contact us by creating a support ticket in the Signicat Dashboard.
Once you have access, you can begin testing the product. For details on test data, see our KvK Dataservice information:
Using the API
Step-by-step guide
You can complete sample flows using the test data provided by KvK Dataservice.
A basic process varies, but will start with the following steps:
Step 1: Obtain an access token
Acquire an access token using the OAuth 2.0 protocol.
The following is a cURL example of a request to receive an access token:
curl --location --request POST 'https://api.signicat.com/auth/open/connect/token' \
--header 'Authorization: Basic <BASE64-ENCODED CLIENTID:CLIENTSECRET>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'
Step 2: Start the appropriate flow
Call the following endpoint:
POST https://api.signicat.com/risk-flow/instant-flows/authority-check-nl/v1
Form the request body
This example shows all fields that can be included in the request:
{
"external_reference": "my-reference-12345",
"input": {
"organizationId": "90006496",
"urls": {
"success": "https://example.com/success",
"abort": "https://example.com/abort",
"error": "https://example.com/error"
},
"currencyCode": "EUR",
"currencyAmount": "10000"
}
}
The response will contain a URL which will redirect the end-user to the identity proofing process. Note that the transaction ID will be used later on.
{
"data": {
"idpUrl": "https://demo.app.signicat.com/broker/sp/external-service/login?messageId=123abc&transactionId=abc123",
"transactionId": "dcbf7783-1a14-46f4-bda3-382eb223f130"
}
}
Step 3: Perform the identity verification
In this step, you will need to complete identity verification. For details on test data, refer to our KvK Dataservice information.
Once the process is complete, you will be redirected to the URLs from your initial request. If configured, you will then receive a webhook.
Step 4: Get the results
To get the result of the identity verification process, you will need to generate a new access token and call the following endpoint:
GET https://api.signicat.com/risk-flow/instant-flows/authority-check-nl/v1/transactions/{transactionId}/response
An example response looks as follows:
{
"data": {
"idpUrl": "https://kyctest.sandbox.qa.signicat.dev/broker/sp/external-service/login?messageId=7e471f0b-4626-4943-95b9-739b925fd9e7&transactionId=09f1a384-fed4-4e4c-b42d-c7de2875c614",
"transactionId": "dcbf7783-1a14-46f4-bda3-382eb023f130",
"results": {
"finalResult": "Review",
"functionaryMatch": "Partial Match",
"hasAuthority": "ND",
"hasLimitation": "Yes",
"reasoning": "Functionary has limitation in action: RDW eDienst Kentekendiensten"
},
"organizationDetails": {
"organizationId": "90006496",
"name": "Gemachtigde B.V.",
"legalForm": "Besloten Vennootschap",
"address": "Hoge Kaart 161555598896117373 brasschaatWalloniëBelgië"
},
"applicantDetails": {
"initial": "E",
"lastName": "Gemachtigde",
"dob": "19750725",
"idpId": "FANTASYBANK1234567890",
"legalLastNamePrefix": "de",
"legalLastName": "Gemachtigde",
"preferredLastNamePrefix": "de",
"preferredLastName": "Vries-Jansen",
"partnerLastNamePrefix": "de",
"partnerLastName": "Jansen"
},
"matchedFunctionary": {
"nameMatch": "Yes",
"dobMatch": "No",
"firstName": "Eerste",
"lastName": "Gemachtigde",
"authorityType": "Beperkte volmacht",
"functionaryType": "gemachtigde",
"functionaryRole": "Gevolmachtigde",
"functionaryTitle": "Kentekendienst",
"authorityLimitationInCurrencyAmount": "",
"authorityLimitationInCurrencyCode": "",
"grantedAuthorityLimitationCurrencyAmount": "1000000",
"grantedAuthorityLimitationCurrencyCode": "EUR",
"authorityLimitationInAction": "RDW eDienst Kentekendiensten"
},
"otherFunctionaries": {
"functionary": [
{
"naturalPerson": "Yes",
"nameMatch": "No",
"dobMatch": "No",
"firstName": "Jasper",
"lastName": "Klinkerberg 1615555988961",
"dob": "19960414",
"authorityType": "Alleen/zelfstandig bevoegd",
"functionaryType": "bestuursfunctie",
"functionaryRole": "Bestuurder",
"functionarTitle": "Directeur"
},
{
"naturalPerson": "Yes",
"nameMatch": "Yes",
"dobMatch": "No",
"firstName": "Eerste",
"lastName": "Gemachtigde",
"dob": "19990909",
"functionaryType": "gemachtigde",
"functionaryRole": "Gevolmachtigde",
"functionarTitle": "Kentekendienst",
"grantedAuthority": "Beperkte volmacht",
"grantedAuthorityLimitationCurrencyAmount": "1000000",
"grantedAuthorityLimitationCurrencyCode": "EUR",
"authorityLimitationInAction": "RDW eDienst Kentekendiensten"
},
{
"naturalPerson": "Yes",
"nameMatch": "No",
"dobMatch": "No",
"firstName": "Tweede",
"lastName": "Gemachtigde",
"dob": "19880808",
"functionaryType": "gemachtigde",
"functionaryRole": "Gevolmachtigde",
"functionarTitle": "Schorser",
"grantedAuthority": "Beperkte volmacht",
"grantedAuthorityLimitationCurrencyAmount": "1000000",
"grantedAuthorityLimitationCurrencyCode": "EUR",
"authorityLimitationInAction": "RDW eDienst Schorsen Voertuigen"
}
]
},
"rawKvkResponse": "rawKvkDatasJsonString"
}
}
The response explained
The result section consists of five different attributes:
finalResult: The final result can be one of three different states:Pass,RevieworFail.- When the result is
Fail, there was either no match between the person data from iDIN and the authorised functionaries or there was a match, but the matched functionary has no authority. - The
Passresult indicates an exact match, confirming that both date of birth and name match a functionary with full authority for the provided organisation. - The
Reviewresult means that there was either a partial match on a functionary with authority or that the authority of the matched functionary is limited in some way. There are many limitations to functionaries authority, an example being that the person only has authority in conjunction with another person.
- When the result is
functionaryMatch: This is information on the type of match, whether there was a match on the name and/or date of birth or no match at all.hasAuthority: This indicates whether the matched functionary has authority or not. This can also result inNDif it was not possible to determine if the person has authority or not.hasLimitation: This indicates whether the matched functionary has any limitation to their authority. This will always beYesorNo.reasoning: This will provide a reasoning as to why the functionary has authority or not.
The rest of the response includes the applicant information, the organisational information, the potential matched functionary information and information on all other functionaries that have authority.
API reference and test data
In our InstantAuthority API reference, you can find information about the available endpoints and properties, as well as sample requests and responses. You can complete sample flows using the test data provided by KvK Dataservice.