API Calls
Set up: POST to https://env.zignsec.com/v2/eid/idin_age
Result: GET from https://env.zignsec.com/v2/eid/sessionid
where env is API or test sessionid is the session identifier retrieved from the setup call, named id in the response.
Call Sequence
- Step 1. Set up session
The returnedredirect_urlis used for starting the browser workflow, identified bysessionid. - Step 2. Run the login workflow
Simply navigate to theredirect_urlin a web browser. The workflow’s user interactions are very specific for the country and bank, and may include an external device like the Swedish Mobile BankID. - Step 3. Get status/results
Collect status and data about the logged in person, using the unique workflowsessionidcode.
Make this call during or after the workflow is completed. The workflow can signal the status pending, completed or error (exception, user abort, timeout) via a browser redirect to thetargetURL and/or via a configured webhook.
There is also JavaScript notification via this Window.postMessage() event.
Step 1. Set up session
POST to https://env.zignsec.com/v2/eid/idin_age
whereenv is API or test
Request Parameters
JSON example:
| Parameter | Description | Required |
|---|---|---|
relaystate | This optional parameter will be returned to you at the redirect back to your server. Use it to link an unique ID of your choice that you can parse. If not relaystate is specified, ZignSec will automatically set the ZignSec’s unique session identifier, the RequestID token here. Example: | No |
target | If this parameter is supplied the browser session will finally be redirected to this URL-value. The URL-parameter value must be URL-encoded. Example: target=http%3A%2F%2Flocalhost%3A8080%2Fzignsec%2Freturn will result in a browser redirect to for examplehttp://localhost:8080/zignsec/return?relaystate=96a09f3f-b764-4ed0-b9e8-2b29d95dcf15&service=eIDBasic where relaystate is ZignSec’s session token (RequestID) which can be used to to retrieve the results from the login session. | No |
targetError | targetError works as target except it is navigated on user cancel or error situations. | No |
webhook | URL. The result will be send to this URL by POST method. | No |
webhook_email | Email address. The result will be send to this Email. | No |
Response
Each request returns a response with status and details. Both the request and the status request follow the same response structure described below.
id | A unique session identifier generated for each workflow instance. |
errors | A JSON array of error conditions, see error handling. |
redirect_url | The URL that the user needs to be redirected to, to complete the data via the web interface. It is possible to load the URL in an iframe. |
Error codes
| Code | Description |
MISSING_CONFIG | Your account has a missing config, contact ZignSec for help |
INVALID_REQUEST | Something unexpected has gone wrong, contact ZignSec for help |
Step 2. Run the login workflow
Simply navigate to the [redirect_url] to start the login workflow in a browser. It may be convenient to load the URL into an HTML IFrame element to get a windowed login integration in an existing web site.
Step 3. Get status/results
GET from https://env.zignsec.com/v2/eid/sessionid
where env is API or testsessionid is retrieved in the setup call (named ‘id’ in the step 1 response).
How To Get Notified of Workflow Finished:
There is both active and passive notification for when the workflow is finished:
- Callback: Set Target URL parameter in step 1 and when the target URL is navigated you can do the above collect-GET.
- Webhook. To set up a webhook URL for callback, contact ZignSec. Results will be posted to the URL, see this example.
- Polling: Repeatedly call the above collect-GET until the results contain a final result.
Response
id | A unique session identifier generated for each workflow instance. | ||||||
errors | A JSON array of error conditions, see error handling. | ||||||
result | Note: This node is missing (deemed unnecessary) if the authentication is successful – i.e., when an identity node is present. An object that describes the main result of the service call. It contains the following parameters:
| ||||||
identity | This identity node contains one special Boolean field AgeApproved which is set to true when the identified person has the required age. | ||||||
IdinAgeChecked | The IdinAgeChecked node contains the following items:
|
Example response
{
"id": "ef17fe5a-a310-4b26-809a-93d0eef4ef57",
"errors": [],
"identity": {
"CountryCode": "NL",
"IdProviderName": "iDin",
"IdentificationDate": "2020-02-26T14:59:21.6055264Z",
"IdProviderRequestId": 1255120,
"AgeApproved": true
},
"IdinAgeChecked": {
"AgeCheckId": 1255120,
"Status": 6,
"StatusText": "Approved"
},
"result": {
"identity": {
"state": "FINISHED"
}
}
}