Digital Onboarding

Trapets API

326 views August 28, 2017 November 30, 2018 1

Overview

Trapets enables screening of customers against sanctions, OFAC and PEP lists for KYC purposes. Please refer to the Trapets KYC product sheet for more information. 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 \
    -H "Content-Type: application/json" \
    -H "Cache-Control: no-cache" \
    -H "Authorization: Bearer <OIDC ACCESS TOKEN>" \
    -d '{ \
    "serviceName":"SANCTION", \ "queryAttributes":[ \
    { \
    } \
    ], \
    "attributeId":"1111", \ "name":"John Smith", \ "birthDate":"1957-07-30", \
    "keywords": [], \
    "countries": [], \ "isSoundEx": false \
    "matchAllNames":true, \ "useSoundEx":true \
    }' \
    "
    <ENVIRONMENT>/trapets/query"​
Example response
[
        {
        "attributeId": "1111",
        "individuals": [
        {
        "id": 17,
        "attributeId": "1111",
        "hitRating": 1,
        "externalId": "833",
        "name": "John William Landon Smith",
        "postDate": "2013-06-24T00:00:00",
        "lastUpdate": "2017-05-11T14:04:59.33",
        "sourceName": "EU_GLOBAL",
        "listType": "SANCTION",
        "comment": "",
        "xml": "
<ENTITY Id=\"833\" Type=\"P\" leg...REMOVED FOR
        BREVITY...TH></ENTITY>",
        "aliases": [
        "Jonathan William Landon Smith",
        "Jonathan William Smith",
        "Jonathan Landon Smith",
        "John William Smith",
        "John Landon Smith"
        ],
        "addresses": [
        "XXX",
        "australia",
        "new zealand"
        ],
        "externalUrls": [
        "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2007:186:0024:
        0028:EN:PDF",
        "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2002:139:0009:
        0022:EN:PDF",
        "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2013:172:0001:
        0003:EN:PDF",
        "http://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32011R0036&f
        rom=EN"
        ],
        "isMale": true,
        "title": "Mr",
        "originalBirthDate": "1957-07-30"
        }
        ],
        "countries": [],
        "entities": [
        {
        "id": 139,
        "attributeId": "1111",
        "hitRating": 1,
        "externalId": "329",
        "name": "Force of War",
        "postDate": "2012-04-12T00:00:00",
        "lastUpdate": "2017-05-16T12:36:38.257",
        "sourceName": "EU_GLOBAL",
        "listType": "SANCTION",
        "comment": "",
        "xml": "<ENTITY Id=\"329\" Type=\"E\" le...REMOVED FOR
        BREVITY...ME></ENTITY>",
        "aliases": [
        "ForceOfWar",
        "Force of War/ War Army",
        "Order of the Inferno",
        " ",
        " / ",
        "μ μ ",
        "μ ",
        "μ ",
        " μ ",
        "Force de guerre",
        "Ordre de l'Enfer",
        "μ μ μ () ",
        " ",
        " „ “",
        "Macht des Krieges",
        "Orden des Infernos"
        ],
        "addresses": [],
        "externalUrls": [
        "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2009:303:0039:
        0059:EN:PDF",
        "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2012:103:0042:
        0044:EN:PDF",
        "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2002:139:0009:
        0022:EN:PDF"
        ]
        }
        ]
        }
        ]
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 31661 alpha2 code of the country.
ThreeLetter String The ISO 31661 alpha2 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

Was this helpful?

Related Articles