This API support an integration of the Signant Customer Due Diligence (CDD) measure with CDD owner business applications.
The purpose of this API is to enable the CDD owner to initiate CDD measures for one or more clients, and to collect CDD documentation and information to its respective customer record.
The CDD API
The API is a .NET Core REST based API that you can call using regular HTTP/HTTPS requests.
Service address: https://test3.signant.no/cdd/api/
The basic concept
The sequence diagram below illustrates the steps involved in order to perform the CDD on a single customer. For recurring measures the step 2-7 may be executed in a batch operation over the desired collection of clients.
The CDD API steps
1. |
The CDD owner initiate a CDD request. |
2. |
Integrated system create a CDD request. This step creates a CDD request ID and leaves a callback URL in the Signant CDD engine. |
3. |
Return the CDD request ID to the integrated system. Integrated system constructs the client dedicated URL. |
4. |
Notify the customer of a CDD measure to be performed. |
5. |
Customer end user navigates to the client dedicated URL to access the CDD form. |
6. |
Signant CDD signals the integrated system of a completed CDD measure. |
7. |
Integrated system request the CDD data |
8. |
Signant CDD transfer CDD data to the integrated system. |
9. |
CDD owner view and validates the collected CDD documentation and information entered by the customer end user. |
Roles in the sequence diagram
CDD owner - The entity or company obliged to perform Customer Due Diligence.
Integrated system - Business application used by the CDD owner to collect customer data and identifying information.
Signant CDD - Signant API and services to perform CDD measures.
End user - A natural person representing either himself for identification of natural person, or the legal representative of a non natural person.
Security
The Signant CDD API require the following credentials in each function call:
API Key |
A key identifying the integrator system. |
Merchant handle |
A handle identifying the CDD owner. |
Access code |
Access code to enable CDD owner usage of the API. |
The API key should be embedded by the vendor of integrator system.
The Merchant handle and Access code should be configurable, and the CDD owner should be able to enter these values into the integrator system.
The credentials are provided to the REST API as HTTP headers, and the header names to use are:
x-api-key
x-merchant-handle
x-merchant-accesscode
Function - Create Request (GET from api/request/create)
The Create Request function initialize a CDD request and must be executed from the integrated system.
Function parameters.
Name |
Description |
Required |
|---|---|---|
category |
which category of CDD request we want. Is it a personal CDD request or a company one. Available options are personal and company. |
Yes |
callbackUrl |
The URL that Signant CDD should call back to once the end user has filled in and signed the requested data. If not provided the callback url configured for the integrator will be used. |
No |
Return value
Name |
Description |
Required |
|---|---|---|
ID |
The CDD_ID identifies the CDD Request, and is the link between CDD data to the Customer/Client in the integrated system. The CDD_ID is returned in the body content and must be kept by the integrator system for later inquiries related to the requested CDD measure. |
Yes |
Code sample - CDD API Create Request
using (var client = new HttpClient()) { client.DefaultRequestHeaders.Add("X-Api-Key", "<ApiKey>"); client.DefaultRequestHeaders.Add("X-Merchant-Handle", "<Merchant_Handle>"); client.DefaultRequestHeaders.Add("X-Merchant-AccessCode","<Merchant_AccessCode>");
var response = client.GetAsync("https://signant.com/cdd/api/request/create? category=<category>&callbackUrl=<callbackUrl>").Result; var requestId = response.Content.ReadAsStringAsync().Result; } |
Client dedicated URL to the CDD form
The CDD request ID returned by the Create Request is to be used in a dedicated URL to the CDD form like this:
This URL can be distributed and presented to the customer in your customer portal or simply sent by mail to the respective customer.
Function - Get Data (GET from api/data/get/<id>)
<id> - The CDD request ID also used in the customer dedicated customer path of the url is the request id.
Sample code - Get Data
using (var client = new HttpClient()) { client.DefaultRequestHeaders.Add("X-Api-Key", "<ApiKey>"); client.DefaultRequestHeaders.Add("X-Merchant-Handle", "<Merchant_Handle>"); client.DefaultRequestHeaders.Add("X-Merchant-AccessCode","<Merchant_AccessCode>");
var response = client.GetAsync("https://signant.com/cdd/api/data/get/<CDD request ID>").Result; } |
Return Value
The Get Data function returns a zip file named <request id>.zip containing the signed document, related files and a json file with the data from the form used. This is returned as a binary stream with content type "application/octet-stream".
Sample response header
api-supported-versions: 1.0 content-disposition: attachment; filename=4ffef7decd6f4347851fbc737e9a4e4c.zip; filename*=UTF- 8''4ffef7decd6f4347851fbc737e9a4e4c.zip content-length: 51117 content-type: application/octet-stream date: Thu,23 Jun 2022 09:35:10 GMT server: Microsoft- IIS/10.0 x-powered-by: ASP.NET |
Callback
There is a service that monitors the CDD data looking for CDD requests where the data has been entered and signed by the end user. When it finds such requests it will perform a callback to the integrated system based on the callback url set in the request or the callback address configured for the integrated system. The callback performed is a regular HTTP/HTTPS call to an web url.
Url
Which Url is called is decided from the CallbackUrl parameter provided when creating the request or by a default callback Url configured for you as an integrator.
Parameters
The callback will always have a query param with the name "r" that contains the CDD request id.
Security
When performing a callback you may want to add some security so not everyone can freely call the callback endpoint. At this pont we're supporting basic authentication, authentication by url token and configuring
custom http headers for you as a integrator.
Basic Authentication
On your integrator profile it is possible to add a username and password. These will be provided in the form of basic authentication on every callback made.
Url Token
If you want to add a security token for a request you can add it to the callback url provided when a request is created and it will be sent back to you upon callback.
Custom Headers
On your integrator profile it is also possible to configure custom http headers. These headers will be added as request headers on any callback made. This can include API keys or other security data.
Internal functions.
