Using Pensure, our API and Testing

This document describes how to set up and use the Pensure API both for testing and production purposes.
All necessary documentation for understanding and describing the API should be contained in this document.

The testing environment located on:
https://demo.pensure.dk , and your subdomain:
https://(yourcompany).demo.pensure.dk , can only be used with NemID testing users provisioned by Nets.
We have several test users to allow you to pass the NemID step. Gain access to the test users by e-mail request.

1. Description of the user journey

The user's journey through our system starts from either a user entering the flow via one of your created apps on Pensure e.g. https://(yourcompany).demo.pensure.dk/onboarding
or through calling our API to start the flow at
https://api.demo.pensure.dk/api/crm/v1/flow/questions/(name)

The following is a description of these two paths through the flow, so you can follow along with whichever solution you are implementing.

1.1 Using the Pensure UI

The user enters the flow with a url to Pensure
This url can contain a key from you site, so you can identify the user when we call back through the webhook and the redirect. By setting a url parameter; ?l=(your customer identifier). There is no limitations on the string length, but remind the general rule of url length and the identifier must not of contain any personal information like a social security number.

It is also possible to pass custom data though the flow. By providing xparam=(string of data) in the start, the same data will be part of the webhook content and the redirect url. (remember to urlencode/escape the xparam value)

1.1.1 Specific for the Demo environemnt

In the Demo environment it also possible to specify a alternative webhook url and a forward url. This gives the opportunity to work on localhost.
demo-webhookurl=(url) will override the default webhook url.
demo-forwardurl=(url) will override the default redirect url. (remember to urlencode/escape the urls).
These two parameters are ignored in production.

The user ends the flow, and the webhook is called
This webhook call will contain some metadata, including the url parameter (customer identifier and xparam) if present. When a succesive response is made from the webhook the browser will be redirected back to your site, including the url parameter (customer identifier and xparam) if present.

You call one or more APIs And ends your call with the exported method.

1.2 Using the Pensure API

You send a request to https://api.demo.pensure.dk/api/crm/v1/flow/questions/(name)
This request needs to include your API keys. You will then receive a response with the data needed to display the correct question.

You then post the data for this question
You will then get the next page in the flow, and the response will look the same as the response described above.

2. Weebhook and Redirect

The webhook is called at the end of the flow.

2.1 Webhook

The content of the webhook call will contain a set of properties:

{
   state: string, // (complete)
   apiToken: string, // (api token, use with the pensure api)
   identity: string, // (customer identity or we can provide social security number)
   xparam: string,   // Data being passed in the start of the flow
   demo: boolean, // true if a test user
   providers: string[] // name(s) of the provider
   flowQuestions: string[]  // name(s) of question flows
   documents: string[] // name(s) of documents
   uploads: string[] // name(s) of upload files
}
field
nullable
description
state
complete
apiToken
token to be used in the API callscomplete
identity
this can be a key you specify in the flow start, or SSN we provide
xparam
true
data provided in url on start
demo
always false in demo env., but can be true in production if internal testing is being done
providers
array of providers; pensionsInfo
flowQuestions
array of packages names
documents
array of available documents names
uploads

array of upload file names

Content:

{
 "apiToken": "CfDJ8Pwq.....e6m2E1M6s",
 "demo": false,
 "identity": "68A5755E-A0A0-4DC2-8AB6-15C7E24B6AF4",
 "xparam": "answer=42",
 "providers": ["pensionsinfo"],
 "state": "complete"
}

3. API

Short description of environment, and methods followed by examples.

Environment URLs
Demo
https://api.demo.pensure.dk
Prod
https://api.pensure.dk

3.1 Security

For all calls to the API, two security headers must be included.

ApiToken
This token will be provided runtime through the webhook result and named ApiToken.
ApiKey
A static key (guid), provided manually.

Example of receiving pensionsinfo pdf through the api:

curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/providers
/pensionsinfo/file/pdf`

3.2 API Methods

3.2.1 Gateway

Last thing first. When you are finished collecting data from the various API's, you must call exported as the very last.
This is important since that request will mark the user's data as received by you, lock it and process it.
All gateway methods are within this path: /api/crm/v1/gateway/

Method for gateway exported

When this method is called, all data will be removed shortly afterwards.
Path: exported     Method: POST
It is posssible to put a failure status on the url like: exported?failed=(some status text here)

Example:
curl -X POST -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/gateway/exported

3.2.2 Pensionsinfo

All PensionsInfo methods is within this path: /api/crm/v1/providers/pensionsinfo/

Method for PensionsInfo PDF

Path: file/pdf    Method: GET
Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/providers/pensionsinfo/file/pdf
Response: will be the binary pdf file.

Method for PensionsInfo Data (json)

Path: file/data     Method: GET
Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/providers/pensionsinfo/file/data
Response: The raw output from PensionsInfo in json format.

3.2.3 flowQuestions

All flow question methods is within this path: /api/crm/v1/flow/questions/(name)

Method for flowQuestions Data (json)

Path: file/data    Method: GET
Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/flow/questions/(name)/file/data
The actual response varies since it depends on the question package

Method for flowQuestions PDF

Path: file/pdf    Method: GET
Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/flow/questions/(name)/file/pdf
By default, the pdf is not created. So please inform us if it is needed.

3.2.4 Documents

If generated documents are part of the flow, they will have this path: documents/(name)/*
The webhook will be called either when the document is generated, or signed if that is required.

Documents file (binary)

The binary document file.
Path: file/binary    Method: GET
Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/documents/(id)/file/binary

Documents data (json)

Some metadata of the file.
Path: file/data    Method: GET

Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/documents/(id)/file/info

Response:

{
 id: string,
 prettyPath: string,
 templateFilename: string,
 prettyFilename: string,
 contentType: string,
 isSigned: boolean,
 timestampUtc: number
}
3.2.5 Uploads

If user is uploading any files, they will have this path: uploads/(name)/*

Uploads file (binary)

The binary document file.
Path: file    Method: GET
Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/uploads/(id)/file/binary

Uploads data (json)

Path: file    Method: GET
Example: curl -v -H "Authorization: Bearer (ApiToken)" -H "X-Pensure-ApiKey: (ApiKey)" https://api.demo.pensure.dk/api/crm/v1/uploads/(id)/file/data

4. Testing

To view test related documentation, request access