NAV Navbar
javascript csharp java python

Introduction

Get started easily with our powerful, easy-to-use API! With the API your application can send and retrieve PEP and sanction data. There are several endpoints for different tasks:

PEP/Sanction screening process

In Pliance the screening process consist of these steps:

  1. Start by registering a Person or Company with the corresponding endpoint with your data.
  2. Retrieve the PEP and Sanction matches with the endpoint.
  3. Retrive the watchlist data from the endpoint and review the matches.
  4. Classify all the matches, choose between Unknown, False Positive and Match.
  5. Archive the person when the person is no longer a customer.
  6. Delete the person from the service, for example if they stop being a customer or to comply with GDPR.

Installation

.Net

dotnet add package Pliance.NET-SDK

Authentication

Authentication in Pliance is done with JWT.

You will need to add the generated authorization token to the request header of all request.

Authorization : Bearer token

Generating JSON Web Token

Generate your own JSON Web Token with a username and userid with the provided secret.

header = {
    "typ": "JWT",
    "alg": "HS256"
}

body = {
    "iat": 1555495956,
    "nbf": 1555495956,
    "exp": 1555496256,
    "aud": "pliance.io",
    "iss": "Customer",
    "given_name": "Username", // username
    "sub": "1337" // userid)
}

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

First request

Now its time to do the first request. We provide a simple endpoint for testing the authentication.

curl -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" -XGET /api/ping

Examples

You can find all the code for this quickstart guide, including runnable sample apps, on Github.

Examples:

using System;
using System.Net.Http;
using System;
using System.IdentityModel.Tokens;
using System.Security.Claims;
using System.Security.Cryptography;
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http.Headers;
using Microsoft.IdentityModel.Tokens;
using System.Text;
using System.Security.Cryptography.X509Certificates;
using System.Security.Authentication;

namespace Example
{
    class Program
    {
        static void Main(string[] args)
        {
            var handler = new HttpClientHandler();
            handler.ClientCertificateOptions = ClientCertificateOption.Manual;
            handler.SslProtocols = SslProtocols.Tls12;
            handler.ClientCertificates.Add(new X509Certificate2("client.pfx"));

            var client = new HttpClient(handler);
            client.BaseAddress = new Uri("https://test-stage4.pliance.io/api/");
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", CreateJwtToken("TEST", "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"));

            var result = client.GetStringAsync("Ping").Result;

            Console.WriteLine($"Response: {result}");
        }

        private static string CreateJwtToken(string issuer, string secret)
        {
            var handler = new JwtSecurityTokenHandler();
            var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secret));
            var token = handler.CreateToken(new SecurityTokenDescriptor
            {
                Issuer = issuer,
                Audience = "pliance.io",
                Expires = DateTime.UtcNow.AddSeconds(300),
                Subject = new ClaimsIdentity(new Claim[] { new Claim("given_name", "Name of user"), new Claim("sub", "id of user") }),
                SigningCredentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256Signature, SecurityAlgorithms.Sha512Digest)
            });

            var tokenString = handler.WriteToken(token);

            return tokenString;
        }
    }
}

package com.pliance.app;

import java.io.BufferedReader;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.security.KeyStore;
import java.security.SecureRandom;
import javax.net.ssl.HttpsURLConnection;
import javax.net.ssl.KeyManager;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.SSLContext;
import javax.crypto.spec.SecretKeySpec;
import java.security.Key;
import io.jsonwebtoken.*;
import java.util.Date;

public class App {
    public static void main(String[] args) {
        try {
            KeyStore clientStore = KeyStore.getInstance("PKCS12");
            clientStore.load(new FileInputStream(new File("client.pfx")), "".toCharArray());
            KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
            kmf.init(clientStore, "".toCharArray());
            KeyManager[] kms = kmf.getKeyManagers();
            SSLContext sslContext = SSLContext.getInstance("TLS");
            sslContext.init(kms, null, new SecureRandom());
            URL url = new URL("https://test-stage4.pliance.io/api/Ping");
            HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Authorization", "Bearer " + createJWT("2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b", "id", "TEST"));
            conn.setSSLSocketFactory(sslContext.getSocketFactory());

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
            }

            BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));
            String output;
            System.out.println("Output from Server .... ");
            while ((output = br.readLine()) != null) {
                System.out.println(output);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static String createJWT(String secret, String id, String issuer) {

        SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;
        long nowMillis = System.currentTimeMillis();
        Date now = new Date(nowMillis);
        byte[] apiKeySecretBytes = secret.getBytes();
        Key signingKey = new SecretKeySpec(apiKeySecretBytes, signatureAlgorithm.getJcaName());
        long expMillis = nowMillis + 1000*300;
        Date exp = new Date(expMillis);
        JwtBuilder builder = Jwts.builder().setId("id").setAudience("pliance.io").setIssuedAt(now).setExpiration(exp).setSubject("1337").setIssuer(issuer)
                .signWith(signatureAlgorithm, signingKey);

        return builder.compact();
    }
}

#!/usr/bin/python3

import requests
import jwt #pip install pyjwt
import datetime

import contextlib
import os
import requests
import ssl
import tempfile
import OpenSSL.crypto #pip install pyopenssl

#https://gist.github.com/erikbern/756b1d8df2d1487497d29b90e81f8068
@contextlib.contextmanager
def pfx_to_pem(pfx_path, pfx_password):
    ''' Decrypts the .pfx file to be used with requests. '''
    with tempfile.NamedTemporaryFile(suffix='.pem') as t_pem:
        f_pem = open(t_pem.name, 'wb')
        pfx = open(pfx_path, 'rb').read()
        p12 = OpenSSL.crypto.load_pkcs12(pfx, pfx_password)
        f_pem.write(OpenSSL.crypto.dump_privatekey(OpenSSL.crypto.FILETYPE_PEM, p12.get_privatekey()))
        f_pem.write(OpenSSL.crypto.dump_certificate(OpenSSL.crypto.FILETYPE_PEM, p12.get_certificate()))
        ca = p12.get_ca_certificates()
        if ca is not None:
            for cert in ca:
                f_pem.write(OpenSSL.crypto.dump_certificate(OpenSSL.crypto.FILETYPE_PEM, cert))
        f_pem.close()
        yield t_pem.name

key = "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"
token = jwt.encode(
    {
        'iat': datetime.datetime.utcnow(),
        'nbf': datetime.datetime.utcnow(),
        'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=300),
        'aud': 'pliance.io',
        'iss': 'TEST',
        'given_name': 'Adam Furtenbach',
        'sub': '1337',
        'id': 1
    }, key, algorithm='HS256')

with pfx_to_pem('client.pfx', '') as cert:    
    r = requests.get('https://test-stage4.pliance.io/api/Ping',
        headers={'Authorization': 'Bearer ' + token.decode('utf-8')},
        verify=True,
        cert=cert)

print(r.text)

let jwt = require('./jwt')
const request = require('request');

let fs = require('fs')
let path = require('path')

let sendRequest = function () {
    var options = {
        headers: {
            'Authorization': 'Bearer ' + jwt.generateJWT('2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b')
        },
        agentOptions: {
            pfx: fs.readFileSync('client.pfx'),
            passphrase: ''
        }    
    };  

    request('https://test-stage4.pliance.io/api/Ping', options, (err, res, body) => {
        if (err) {
            return console.log(err);
        }
        console.log(body);
    });
};

sendRequest();

Person

Register Person

Post a JSON structured like this:

{
    "PersonReferenceId": "ref1",
    "Identity": {
        "Identity": "600714-8841",
        "Country": "se"
    },
    "FirstName": "Vendela",
    "LastName": "Bogren",
    "Gender": "Female",
    "Birthdate": {
        "Year": 1960,
        "Month": 07,
        "Day": 14
    },
    "Addresses": [
        {
            "Country": "se",
            "City": "ESKILSTUNA",
            "Street1": "Jaktstigen",
            "StreetNo": "12",
            "PostalCode": "632 31"
        }
    ],
    "Options": {
        "Order": "Strict",
        "Fuzziness": "Metaphone"
    }
}

The above command returns JSON structured like this:

{
    "hits": [
        [
            {
                "matchId": "list-13935",
                "matchedFirstName": [
                    {
                        "text": "Vendela",
                        "isMatch": true
                    }
                ],
                "matchedLastName": [
                    {
                        "text": "Bogren",
                        "isMatch": true
                    }
                ],
                "isPep": true,
                "isRca": false,
                "isSanction": false,
                "classification": "Unknown",
                "aliasId": "55601e25d6c885e8e7c549970315016196bb01c9ff22aa796d81ba5469c87a8c"
            }
        ]
    ],
    "status": "Success",
    "success": true
}

The register person endpoint allows a person to be registered for PEP and Sanction screening, and automatic monitoring. This is the first step in the the process. It also returns all the hits.

HTTP Request

PUT /api/PersonCommand

Data Parameters

Name Type Values Description Required
PersonReferenceId string A unique identifier yes
Identity PersonIdentity yes
FirstName string yes
LastName string yes
Gender string Male, Female no
Birthdate Birthdate no
Addresses Address[] no
Options RegisterPersonOptions no

Types

PersonIdentity
Name type Values Description Required
Identity string National Identification Number/Swedish Personal Number
Country string In ISO 3166 format
Birthdate
Name type Values Description Required
Year int 0-9999
Month int 1-12
Day int 1-31
Address
Name type Values Description Required
Country string In ISO 3166 format
City string
Street1 string
Street2 string
StreetNo string
PostalCode string
RegisterPersonOptions
Name type Values Description Required
Order string Any, Strict, Exact Used to set the match order for names
Fuzziness string Metaphone, Simple, Diacritics Set the algorithm used to match names
Fuzziness: Simple

Simple case insensitive compare

Input List Match
Linnéa Linnéa x
Linnea Linnéa
Linea Linnéa
Lina Linnéa
Lnnea Linnéa
Fuzziness: Diacritics

Smash diacritics before insensitive compare

Input List Match
Linnéa Linnéa x
Linnea Linnéa x
Linea Linnéa
Lina Linnéa
Lnnea Linnéa
Fuzziness: Metaphone

Phonetic compare (https://en.wikipedia.org/wiki/Metaphone)

Input List Match
Linnéa Linnéa x
Linnea Linnéa x
Linea Linnéa x
Lina Linnéa x
Lnnea Linnéa x
Order: Any

Names can be matched in any order

Input List Match
Osama Osama bin Laden x
bin Osama bin Laden x
Laden Osama bin Laden x
bin Laden Osama bin Laden x
Laden bin Osama Osama bin Laden x
Osama bin Laden Osama bin Laden x
Order: Strict

Names must appear in the same order

Input List Match
Osama Osama bin Laden x
bin Osama bin Laden x
Laden Osama bin Laden x
bin Laden Osama bin Laden x
Laden bin Osama Osama bin Laden
Osama bin Laden Osama bin Laden x
Order: Exact

All names must match, and appear in the same order

Input List Match
Osama Osama bin Laden
bin Osama bin Laden
Laden Osama bin Laden
bin Laden Osama bin Laden
Laden bin Osama Osama bin Laden
Osama bin Laden Osama bin Laden x

View Person

The view person is used to retrieve a person and all the matches.

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true,
    "data": {
        "personReferenceId": "ref1",
        "identity": {
            "identity": "19600714-8841",
            "country": "se"
        },
        "firstName": "Vendela",
        "lastName": "Bogren",
        "birthdate": "1960-07-14",
        "gender": "Female",
        "addresses": [
            {
                "street1": "Jaktstigen",
                "street2": "",
                "city": "ESKILSTUNA",
                "streetNo": "12",
                "postalCode": "632 31",
                "country": "se"
            }
        ],
        "hits": [
        [
            {
                "matchId": "list-13935",
                "matchedFirstName": [
                    {
                        "text": "Vendela",
                        "isMatch": true
                    }
                ],
                "matchedLastName": [
                    {
                        "text": "Bogren",
                        "isMatch": true
                    }
                ],
                "gender": "Unknown",
                "isPep": true,
                "isRca": false,
                "isSanction": false,
                "classification": "Unknown",
                "aliasId": "55601e25d6c885e8e7c549970315016196bb01c9ff22aa796d81ba5469c87a8c"
            }
        ]
        ]
    }
}

HTTP Request

GET /api/PersonQuery?PersonReferenceId=[string]

Query Parameters

Name type Required
PersonReferenceId string yes

Classify Match

The Classify Match endpoint is used to classify PEP/Sanction matches for a person.

Post a JSON structured like this:

{
    "PersonReferenceId": "ref1",
    "MatchId": "match1",
    "Classification": "Positive"
}

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true
}

HTTP Request

POST /api/PersonCommand/Classify

Data Parameters

Name Type Values Description Required
PersonReferenceId string yes
MatchId string yes
Classification string Unknown, FalsePositive, Positive yes

Archive a person

The archive endpoint allows developers to archive a person. The person will no longer be visible and no longer be monitored, but will remain in the database for auditing.

Post a JSON structured like this:

{
    "PersonReferenceId": "ref1"
}

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true
}

HTTP Request

POST /api/PersonCommand/Archive

Data Parameters

Name Type Values Description Required
PersonReferenceId string yes

Delete Person

The delete person endpoint allows developers to delete a person completely from the system. For example this could be used for remove a person for GDPR compliance.

Post a JSON structured like this:

{
    "PersonReferenceId": "ref1"
}

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true
}

HTTP Request

Delete /api/PersonCommand

Data Parameters

Name Type Values Description Required
PersonReferenceId string yes

Search Person

The Search Person endpoint is used to search persons by name and filter by matches.

The above command returns JSON structured like this:


{
    "status": "Success",
    "success": true,
    "data": {
        "result": [
            {
                "personReferenceId": "ref1",
                "identity": {
                    "Identity": "600714-8841",
                    "Country": "se"
                },
                "firstName": [
                    {
                        "isMatch": false,
                        "text": "Vendela"
                    }
                ],
                "lastName": [
                    {
                        "isMatch": true,
                        "text": "Bogren"
                    }
                ],
                "isPep": false,
                "isRca": false,
                "isSanction": false
            }
        ]
    }
}

HTTP Request

GET /api/PersonQuery/Search?query=[string]&isPep=[boolean]&isRca=[boolean]&isSanction=[boolean]

Query Parameters

Name type Required
query string yes
isPep boolean no
isRca boolean no
isSanction boolean no

Company

Register Company

Post a JSON structured like this:

{
    "CompanyReferenceId": "ref1",
    "Identity": {
        "Identity": "559161-4275",
        "Country": "se"
    },
    "Name": "Pliance AB"
}

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true
}

The register company endpoint is used to register a company for PEP screening of the company beneficiaries.

HTTP Request

PUT /api/CompanyCommand

Data Parameters

Name Type Values Description Required
CompanyReferenceId string A unique identifier for a company yes
Identity CompanyIdentity yes
Name string yes

Types

CompanyIdentity
Name type Values Description Required
Identity string Company Organization number
Country string in ISO 3166 format

View Company

The view company endpoint is used to retrieve a company with all the beneficiaries and their PEP status.

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true,
    "data": {
        "companyReferenceId": "ref1",
        "identity": {
            "Identity": "559161-4275",
            "Country": "se"
        },
        "name": "Pliance AB",
        "graph": {
            "nodes": [{
                "id": 0,
                "name": "Plisec AB",
                "type": "Plisec AB",
                "reference": "559161-4275",
                "isPep": false
            }, {
                "id": 1,
                "name": "Jan Nelson",
                "type": "Person",
                "reference": "19630728-2571",
                "isPep": false
            }, {
                "id": 2,
                "name": "We Go To Eleven AB",
                "type": "Company",
                "reference": "559118-2901",
                "isPep": false
            }, {
                "id": 3,
                "name": "Jonas Holmén",
                "type": "Person",
                "reference": "19670812-1311",
                "isPep": false
            }, {
                "id": 4,
                "name": "Jan-Olof Halvarsson",
                "type": "Person",
                "reference": "19800610-2837",
                "isPep": false
            }],
            "links": [{
                "source": 1,
                "target": 2,
                "type": "Huvudman"
            }, {
                "source": 0,
                "target": 2,
                "type": "Moderbolag"
            }, {
                "source": 3,
                "target": 2,
                "type": "Huvudman"
            }, {
                "source": 4,
                "target": 0,
                "type": "Huvudman"
            }]
        },
        "beneficiaries": [{
            "nationIdentityNumber": "19630728-2571",
            "firstName": "Jan",
            "lastName": "Nelson",
            "isPep": false,
            "engagements": [{
                "registrationNumber": "559118-2901",
                "name": "We Go To Eleven AB"
            }]
        }, {
            "nationIdentityNumber": "19670812-1311",
            "firstName": "Jonas",
            "lastName": "Holmén",
            "isPep": false,
            "engagements": [{
                "registrationNumber": "559118-2901",
                "name": "We Go To Eleven AB"
            }]
        }, {
            "nationIdentityNumber": "19800610-2837",
            "firstName": "Jan-Olof",
            "lastName": "Halvarsson",
            "isPep": false,
            "engagements": []
        }]
    }
}

HTTP Request

GET /api/CompanyQuery?companyReferenceId=[string]

Query Parameters

Name type Required
companyReferenceId string yes

Search Company

The Search Company endpoint is used to search company by name and filter by matches.

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true,
    "data": {
        "result": [
            {
                "companyReferenceId": "ref1",
                "identity": {
                    "Identity": "559161-4275",
                    "Country": "se"
                },
                "names": [
                    {
                        "text": "Pliance AB",
                        "isMatch": true
                    }
                ],
                "isPep": false,
                "isRca": false,
                "isSanction": false
            }
        ]
    }
}

HTTP Request

GET api/CompanyQuery/Search?query=[string]&isPep=[boolean]&isRca=[boolean]&isSanction=[boolean]

Query Parameters

Name type Required
query string yes
isPep boolean no
isRca boolean no
isSanction boolean no

Archive Company

The archive endpoint allows developers to archive a company. It will remain in the database but will no longer visible.

Post a JSON structured like this:

{
    "CompanyReferenceId": "ref1"
}

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true
}

HTTP Request

POST /api/CompanyCommand/Archive

Data Parameters

Name Type Values Description Required
CompanyReferenceId string yes

Delete Company

The delete company endpoint allows developers to delete a company completely from the system.

Post a JSON structured like this:

{
    "CompanyReferenceId": "ref1"
}

The above command returns JSON structured like this:

{
    "status": "Success",
    "success": true
}

HTTP Request

Delete /api/CompanyCommand

Data Parameters

Name Type Values Description Required
CompanyReferenceId string yes

Watchlist

Retrieve Person

The above command returns JSON structured like this:

{
    "data":{
        "listId":"list-3954",
        "NationalIdentificationNumber":"19960106-3143",
        "gender":"Female",
        "names":[
            {
                "firstName":"Selma",
                "lastName":"Söderblom",
                "selectedFirstName":[
                    {
                        "text":"Selma",
                        "isMatch":true
                    }
                ],
                "selectedLastName":[
                    {
                        "text":"Söderblom",
                        "isMatch":true
                    }
                ]
            },
            {
                "firstName":"Selma Anna",
                "lastName":"Söderblom",
                "selectedFirstName":[
                    {
                        "text":"Selma ",
                        "isMatch":true
                    },
                    {
                        "text":" ",
                        "isMatch":false
                    },
                    {
                        "text":"Selma",
                        "isMatch":true
                    }
                ],
                "selectedLastName":[
                    {
                        "text":"Söderblom",
                        "isMatch":true
                    }
                ]
            }],   
            "birthdates":[
                {
                    "circa":false,
                    "year":1996,
                    "month":01,
                    "day":06
                }
            ],
            "addresses":[{}],
            "countries":["se"],
            "isPep":false,
            "isRca":true,
            "isSanction":false,
            "nationalities":[],
            "images":[],
            "roles":[],
            "relations":[
                {
                    "firstName":"Lena",
                    "lastName":"Söderblom",
                    "relationPersonId":"list-279",
                    "isPep":true,
                    "isRca":false,
                    "isSanction":false,
                    "relationType":"Mor"
                }
            ]
    },   
    "status":"Success",
    "success":true
}

The Watchlist endpoint is used to retrieve data from PEP and sanctions lists by the matchId.

HTTP Request

GET /api/WatchlistQuery?id=[string]&FirstName=[string]&LastName=[string]

Query Parameters

Name type Required Description
Id string yes The list Id
FirstName string no
LastName string no
javascript csharp java python