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 |