Trapets API

Overview

Trapets enables screening of customers against sanctions, OFAC and PEP lists for KYC purposes. The API is isolated to a single endpoint/ query, which accepts a parameterized query object that controls the result set.

Using the service

Authentication

All requests must be authenticated by means of an OIDC access token, supplied as an Authorization header of type Bearer. For more instructions on how to obtain such a token, please refer to Accessing Signicat REST services.

Queries

The /query method accepts a DoQuery object which may contain multiple subject queries (QueryAttribute). Each QueryAttribute has a unique ID (AttributeId) so that the result set can be mapped to the request set.

API

Environment	Base URL
Beta	https://beta.signicat.com
Pre-production	https://preprod.signicat.com
Production	https://id.signicat.com

Path	Verb	Content Type	Input	Output
/trapets/query	POST	application/json	DoQuery	List<QueryResult>

Code examples

Example request using cURL

curl -X POST \
  https://preprod.signicat.com/trapets/query \
  -H 'Authorization: Bearer <OIDC ACCESS TOKEN>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "serviceName":"SANCTION",
    "queryAttributes":[
        {
            "attributeId":"1111",
            "name":"Gustaf Nordell",
            "birthDate":"1972-02-16",
            "keywords": [],
            "countries": []
        }
        ]
}'

Example response

[
    {
        "attributeId": "1111",
        "name": "Gustaf Nordell",
        "individuals": [
            {
                "id": 19,
                "attributeId": "1111",
                "hitRating": 1,
                "externalId": "TrapetsTest-14",
                "name": "Nordell, Gustaf",
                "lastUpdate": "2018-11-14T13:43:41.633",
                "sourceName": "EU_GLOBAL",
                "listType": "SANCTION",
                "xml": "<OriginalData>\n<Item><Individual><Name>Nordell, Gustaf</Name><QueryParameter /><ServiceName /><ExternalId>TrapetsTest-14</ExternalId><BirthDate>1977-01-10</BirthDate><Ssn /><Comment /><Attributes><BirthDate>1977-01-10</BirthDate><Title /></Attributes><Aliases><Alias>Nordell, Gustaf</Alias></Aliases><Addresses><Address><Country>Sweden</Country></Address></Addresses><Emails /><ExternalUrls><Url>https://google.com</Url></ExternalUrls><CheckSum>667</CheckSum></Individual></Item></OriginalData>",
                "aliases": [
                    "Nordell, Gustaf"
                ],
                "addresses": [
                    ",,,SWE"
                ],
                "externalUrls": [
                    "https://google.com"
                ],
                "birthDate": "1977-01-10T00:00:00",
                "originalBirthDate": "1977-01-10"
            }
        ],
        "countries": [],
        "entities": []
    }
]

Example using java

Package com.example;
import java.util.List;
import java.util.Objects;
import javax.naming.AuthenticationException;
import org.json.JSONException;
import org.json.JSONObject;
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;
import com.signicat.service.trapets.models.DoQuery;
import com.signicat.service.trapets.models.QueryResult;
import com.signicat.service.trapets.util.Mapper;
public class TrapetsRestClient {
    public static final String PEP = "PEP";
    public static final String SANCTION = "SANCTION";
    private final String url;
    private String oidcUrl;
    private String oidcClientId;
    private String oidcSecret;
    private String token = null;
    public TrapetsRestClient(final String url, final String oidcUrl, final
    String oidcClientId, final String oidcSecret) throws
            AuthenticationException {
        this.url = url;
        this.oidcUrl = oidcUrl;
        this.oidcClientId = oidcClientId;
        this.oidcSecret = oidcSecret;
        JSONObject tokenObj =
                auth(this.oidcUrl, this.oidcClientId, this.oidcSecret);
        try {
            this.token = (String) tokenObj.get("access_token");
        } catch (JSONException ex) {
            throw new AuthenticationException();
        }
        Unirest.setObjectMapper(new Mapper());
    }
    private static JSONObject auth(final String oidcUrl, final String
            oidcClientId, final String oidcSecret) throws AuthenticationException {
        HttpResponse<JsonNode> resp = null;
        try {
            resp = Unirest.post(oidcUrl)
                    .basicAuth(oidcClientId, oidcSecret)
                    .header("accept", "application/json")
                    .header("Content-Type",
                            "application/x-www-form-urlencoded")
                    .field("grant_type", "client_credentials")
                    .field("scope", "trapets.post.query").asJson();
        } catch (final UnirestException e) {
            throw new AuthenticationException("Unable to retrieve access
                    token, please check OIDC url and respective credentials.");
        }
        JSONObject token = resp.getBody().getObject();
        return token;
    }
    public List<QueryResult> doQuery(DoQuery query) throws
            AuthenticationException {
        Objects.requireNonNull(query);
        try {
            return postQuery(query);
        } catch (UnirestException e) {
            try {
                JSONObject tokenSet = auth(this.oidcUrl, this.oidcClientId,
                        this.oidcSecret);
                this.token = (String) tokenSet.get("access_token");
                return postQuery(query);
            } catch (UnirestException | JSONException ex) {
                throw new AuthenticationException();
            }
        }
    }
    private List<QueryResult> postQuery(DoQuery query) throws
            UnirestException {
        HttpResponse<List> response = Unirest.post(url)
                .header("accept", "application/json")
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer " + token)
                .body(query)
                .asObject(List.class);
        return response.getBody();
    }
}

Messages

DoQuery

Name	Type	Description
ServiceName	String	If a value is not supplied, the query will be performed on all services configured on the logged in user. Possible values are “SANCTION” or “PEP”.
QueryAttributes	List<QueryAttribute>	List of query attributes.

QueryAttribute

Name	Type	Description
AttributeId	String	The ID of the QueryAttribute, used for reference in order to be able to map an array of responses to the request set.
Countries optional	List<Countries>	A list of countries. If set to null, any country will be accepted. Due to the nature of the data supplied, either from the list the queries are made from or the service being queried, you might want to leave this field out. PEP is generally more reliable than Sanction (EU + UN).
Name	String	The name of the subject being queried. “Anders Andersson”. The name order does not matter. Some phonetic interpretation is made. The more parts of a name are being submitted, the more the search is narrowed.
BirthDate optional	String	The birthdate in the format of “yyyyMMdd”. If omitted, no filtering on birthdate is made for this QueryAttribute. Items in the KYC database that do not have a birthdate set will not be filtered out.
Ssn optional	String	The SSN (social security number, used in this case to mean the national identification number for the country in question) is generally entered in the format that is used by the issuing country with the two-letter ISO country code as a prefix. Any hyphens or other special characters are omitted. Following is an example of a Swedish national identification number: SE195707210190

Countries

Name	Type	Description
Id	Int	The internal ID of the country. Only used as a reference.
Name	String	The name of the country in English.
TwoLetter	String	The ISO 3166-1 alpha-2 code of the country.
ThreeLetter	String	The ISO 3166-1 alpha-3 code of the country.

QueryResult

Name	Type	Description
AttributeId	String	The ID of the QueryAttribute. It will be identical to the value passed in the DoQuery method.
Countries	List<Countries>	A list of countries matching the QueryAttribute. If this array contains any elements, it means the country supplied is on a sanction list itself.
Entities	List<Entity>	A list of entities matching the QueryAttribute.
Individuals	List<Individual>	A list of individuals matching the QueryAttribute.
Name	String	The name of the result. Usually made up of the names in the QueryAttribute.

Individual

Name	Type	Description
Id	Int	The internal ID. Only used as a reference.
AttributeId	String	The ID of the QueryAttribute. It will be identical to the value passed in DoQuery.
ExternalId	String	The ID used in the source. This combined with the SourceName will be unique.
Name	String	Name of the individual.
PostDate	Datetime	The date of the initial post according to the source.
LastUpdate	Datetime	The date of the last update.
SourceName	String	The name of the source, i.e. “EU_GLOBAL”, “PEP_Edge” or “UN_CONSOLIDATED”.
ListType	String	The type of list, i.e “PEP” or “SANCTION”.
Url	String	URL to the source document.
Comment	String	A comment on this entry, if any.
Xml	String	XML representing the entry, if any was given by the source.
Aliases	String	A list of aliases as strings.
Addresses	String	A list of addresses as strings.
ExternalURLs	String	A list of external URLs as strings. Could refer to documents explaining why this entry was posted, not necessarily the entry itself.
IsMale	Boolean	Indicates the gender. If set to null, it’s not known.
Title	String	The title of the individual, ex: General.
FunctionDescription	String	The function of the individual.
BirthDate	Datetime	The date of birth.
OriginalBirthDate	String	The date of birth from the source. If the system wasn’t able to parse this value, the “BirthDate” will be null and this value might be set.
ItemNumber	String	The SSN, or national identification number, of the individual in the issuing country’s format.
HitRating	Int	Indicates how relevant this list item is to the query. The higher the number, the more accurate, with 5 being the most accurate: Ssn => 5 BirthDate => 4 Year (Birthdate) => 2 Name => 1

Entity

Name	Type	Description
Id	Int	The internal ID. Only used as a reference.
AttributeId	String	The ID of the QueryAttribute. It will be identical to the value passed in the DoQuery method.
ExternalId	String	The ID used in the source. This combined with the SourceName will be unique.
Name	String	Name of the individual.
PostDate	Datetime	The date of the initial post according to the source.
LastUpdate	Datetime	The date of the last update.
SourceName	String	The name of the source, i.e. “EU_GLOBAL”, “PEP_Edge” or “UN_CONSOLIDATED”.
ListType	String	The type of list, i.e “PEP” or “SANCTION”.
Url	String	URL to the source document.
Comment	String	A comment on this entry, if any.
Xml	String	XML representing the entry if any was given by the source.
Aliases	String	A list of aliases as strings.
Addresses	String	A list of addresses as strings.
ExternalURLs	String	A list of external URLs as strings. Could refer to documents explaining why this entry was posted, not necessarily the entry itself.
ItemNumber	String	The SSN, or national identification number, of the individual in the issuing country’s format.
HitRating	Int

Identity verification