API Documentation

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 through 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 an 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 Pension info

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

Using Pensure, our API and Testing