Skip to end of metadata
Go to start of metadata
 Accessing Signicat Rest Services

Overview

In order to consume Signicat REST services, a caller must first acquire an access token in order to be able to authenticate consecutive requests. The access token is retrieved using the OpenID Connect (OIDC) protocol. For more, general information about OpenID Connect, please refer to https://support.signicat.com/display/S2/OpenID+Connect+-+OIDC.

Using the service

Required information

In order to call the OIDC endpoint, you will need:

  • Client ID
  • Client secret
  • Scope

Please refer to https://support.signicat.com to have this information provided for your service.

API

PathVerbContent typeHeaderInputOutput
/oidc/tokenPOSTapplication/x-www-form-urlencodedAuthorization headerTokenRequestTokenResponse

 

Authorization header

When acquiring the access token

The authentication header is your Client ID and Client secret, joined with a colon in between and then base 64 encoded. So, if your client id is

"foo" and your client secret is "bar", then the header value is:

foo:bar -> Zm9vOmJhcg==

 

In your HTTP request to the /oidc/token endpoint, the following header is then added:

Authorization: Basic Zm9vOmJhcg==

When using the access token

When you've received the access token, you will need to apply an authorization header when doing requests to the service resources that you are using. The access token header is:

Authorization: Bearer <YOUR ACCESS TOKEN HERE>

Code examples

Example request using cURL
Example request using Java

Messages

TokenRequest

NameTypeDescription
ScopeStringThe requested scope.
GrantTypeStringThe string "client_credentials".

TokenResponse

NameTypeDescription
AccessTokenStringThe access token.
TokenTypeStringThe string "Bearer".
ScopeStringThe requested scope.
ExpiresInLongMillseconds until the access token expires unless refreshed.

 Companies House API

Overview

Companies House is the United Kingdom registrar of companies and is an executive agency of the government. This entity is responsible for the Companies House API

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. When retrieving the token, the scope client.companieshouse.search.get must be specified.

API

Environment
Base URL
Beta
https://beta.signicat.com
Preproduction
https://preprod.signicat.com
Production
https://id.signicat.com
Path
Verb

Input

Output
/companieshouse/search
GET
        

Search Path Parameters

Search
/companieshouse/search/companies
GETSearch Path ParametersCompanySearch
/company/{companynumber}/officers
GETPerson Search ParametersOfficerList
/company/{companynumber}/persons-with-significant-control
GETPerson Search Parameters PersonWithSignificantControlList
/company/{companynumber}/filing-history
GETFiling History Search ParametersFilingHistoryList

The difference between the methods is that the most generic one (/companieshouse/search) searches across all indexed information (companies, officers and disqualified officers), and the other one searches only in the companies repository. 

Code examples

 

Example using cURL

Search Path Parameters 

Name
Type
Description

q

String

The search term, e.g. company name, company number, director name, address, etc.

items_per_page
optional

IntegerThe number of search results to return per page.

start_index
optional

IntegerThe index of the first result item to return.

 

Person Search Parameters  

Name
Type
Description

company_number

StringThe company number of the list being requested.

items_per_page
optional

IntegerThe number of search results to return per page.

register_type
optional
officers

StringThe register_type determines which officer type is returned for the registers view. Accepted values are:
  • directors
  • secretaries
  • llp-members
The register_type field will only work if registers_view is set to true

register_view
optional

StringDisplay register specific information. If given register is held at Companies House, registers_view set to true and correct register_type specified, only active officers will be returned. Those will also have full date of birth. Accepted values are:
  • true
  • false
Defaults to false

start_index
optional

IntegerThe index of the first result item to return.

order_by
optional
officers

StringThe field by which to order the result set. Possible values are:
  • appointed_on
  • resigned_on
  • surname

Negating the order_by will reverse the order. 
For example, order_by=-surname will give results in descending order of surname

Filing History Search Parameters  

Name
Type
Description

company_number

StringThe company number that the filing history is required for.

category
optional

StringOne or more comma-separated categories to filter by (inclusive).

items_per_page
optional

IntegerThe number of search results to return per page.

start_index
optional

IntegerThe index of the first result item to return.

Messages

Name
Type
Description

etag
optional

StringThe ETag of the resource.

items
optional

List<Item>The results of the completed search. See items.kind for details of each specific result resource returned.

items_per_page
optional

IntegerThe number of search items returned per page.

kind
optional

StringThe type of search response returned. Possible values are:
  • search#all

start_index
optional

IntegerThe index into the entire result set that this result page starts.

total_results
optional

IntegerThe number of further search results available for the current search.

 CompanySearch

Name
Type
Description

etag
optional

StringThe ETag of the resource.

items
optional

List < Item >The results of the completed search.

items_per_page
optional

Integer

The number of search items returned per page. These items include the values that are relative to the company search.

kind
optional

StringThe type of search response returned. Possible values are:
  • search#companies

start_index
optional

IntegerThe index into the entire result set that this result page starts.

total_results
optional

IntegerThe number of further search results available for the current search.

 Item

Name
Type
Description
addressAddressThe address of the company's registered office.
address_snippetStringA single line address. This will be the address that matched within the indexed document, or the primary address otherwise (as returned by the address member).

company_number
companies search

StringThe company registration / incorporation number of the company.

company_status
companies search

EnumThe company status. Possible values are:
  • active
  • dissolved
  • liquidation
  • receivership
  • administration
  • voluntary-arrangement
  • converted-closed
  • insolvency-proceedings

company_type
companies search

EnumThe company type. Possible values are:
  • private-unlimited
  • ltd
  • plc
  • old-public-company
  • private-limited-guarant-nsc-limited-exemption
  • limited-partnership
  • private-limited-guarant-nsc
  • converted-or-closed
  • private-unlimited-nsc
  • private-limited-shares-section-30-exemption
  • assurance-company
  • oversea-company
  • eeig
  • icvc-securities
  • icvc-warrant
  • icvc-umbrella
  • industrial-and-provident-society
  • northern-ireland
  • northern-ireland-other
  • llp
  • royal-charter
  • investment-company-with-variable-capital
  • unregistered-company
  • llp
  • other
  • european-public-limited-liability-company-se

date_of_cessation
optional
companies search

DateThe date the company ended.

date_of_creation
optional
companies search

DateThe date the company was created.

description
optional

StringThe result description.

description_identifier
optional

ArrayAn array of Enumeration types that make up the search description. See search_descriptions_raw.yaml in api-Enumerations
kindString

The type of search result. Depending on the endpoint used possible values are:

  • searchresult#company
  • searchresults#officer
  • searchresults#disqualified-officer
linksObjectThe URL of the search result.
links.selfStringThe URL of the resource being returned by the search item.

matches
optional

MatchesA list of members and arrays of character offset, defining subStrings that matched the search terms.

snippet
optional

StringSummary information for the result, showing additional details that have matched. In the case of companies, this would be previous company names.
titleStringThe title of the search result.

Address 

Name
Type
Description
address_line_1StringThe first line of the address.

address_line_2
optional

StringThe second line of the address.

care_of
optional

StringThe care of name.

country
optional

StringThe country.

locality
optional

StringThe locality e.g London.

po_box
optional

StringThe post-office box number.

postal_code
optional

StringThe postal code e.g CF14 3UZ.
premises
optional
persons with sinificant control
officers
StringThe property name or number.

region
optional

StringThe region e.g Surrey.

Matches 

Name
Type
Description

address_snippet
optional

ArrayAn array of character offset into the address_snippet String. These always occur in pairs, and define the start and end of subStrings in the member address_snippet that matched the search terms.

snippet
optional

ArrayAn array of character offset into the snippet String. These always occur in pairs, and define the start and end of subStrings in the member snippet that matched the search terms. The first character of the String is index 1.

title
optional

ArrayAn array of character offset into the title String. These always occur in pairs, and define the start and end of subStrings in the member title that matched the search terms. The first character of the String is index 1.

 

OfficerList 

Name
Type
Description

active_count

IntegerThe number of active officers in this result set.
etagString

The ETag of the resource.

inactive_countIntegerThe number of officers who have not resigned where the company status is dissolved or converted-closed in this result set.
itemsList<Officer>The list of officers.

items_per_page

IntegerThe number of officers to return per page.

kind

StringThe type of search response returned. Possible values are:
  • officer-list
linksObjectLinks to other resources associated with this officer list resource.
links.selfStringLink to this officer list resource.
resigned_countIntegerThe number of resigned officers in this result set.
start_indexIntegerThe offset into the entire result set that this page starts.

total_results
 optional

IntegerThe total number of officers in this result set.

Officer 

Name
Type
Description

address

AddressThe correspondence address of the officer.
appointed_onDateThe date on which the officer was appointed.
country_of_residence
optional
StringThe officer's country of residence.
date_of_birth
optional
Date of birthDetails of director date of birth.

former_names
optional

List<Former Name>Former names for the officer.
identification
optional
IdentificationOnly one from eea or non-eea can be supplied, not both.
linksObjectLinks to other resources associated with this officer list item.
links.officerObjectLinks to other officer resources associated with this officer list item.
links.officer.appointmentsStringLink to the officer appointment resource that this appointment is associated with.
nameStringCorporate or natural officer name.
nationality
optional
StringThe officer's nationality.
occupation
optional
StringThe officer's job title.
officer_roleStringPossible values are:
  • cic-manager
  • corporate-director
  • corporate-llp-designated-member
  • corporate-llp-member
  • corporate-manager-of-an-eeig
  • corporate-member-of-a-management-organ
  • corporate-member-of-a-supervisory-organ
  • corporate-member-of-an-administrative-organ
  • corporate-nominee-director
  • corporate-nominee-secretary
  • corporate-secretary
  • director
  • general-partner-in-a-limited-partnership
  • judicial-factor
  • limited-partner-in-a-limited-partnership
  • llp-designated-member
  • llp-member
  • manager-of-an-eeig
  • member-of-a-management-organ
  • member-of-a-supervisory-organ
  • member-of-an-administrative-organ
  • nominee-director
  • nominee-secretary
  • person-authorised-to-accept
  • person-authorised-to-represent
  • person-authorised-to-represent-and-accept
  • receiver-and-manager
  • secretary
resigned_onDateThe date on which the officer resigned. 

Date of Birth 

Name
Type
Description

day
optional

IntegerThe day of the date of birth.
monthIntegerThe month of date of birth.
yearIntegerThe year of date of birth.

Former Names 

Name
Type
Description

forenames
optional

StringFormer forenames of the officer.
surname
optional
StringFormer surnames of the officer.

Identification 

Name
Type
Description

identification_type
optional

StringPossible values are:
  • eea
  • non-eea

legal_authority
 optional

StringThe legal authority supervising the company.

legal_form
optional

StringThe legal form of the company as defined by its country of registration.

place_registered
optional

StringPlace registered.

registration_number
optional

StringCompany registration number.

PersonWithSignificantControlList 

Name
Type
Description

active_count

IntegerThe number of active persons with significant control in this result set.
ceased_countIntegerThe number of ceased persons with significant control in this result set.
etagStringThe ETag of the resource.

items

List<Person With Significant Control>The list of persons with significant control

items_per_page

IntegerThe number of persons with significant control to return per page.

kind

StringThe type of search response returned. Possible values are:
  • persons-with-significant-control#list
linksObjectA set of URLs related to the resource, including self.
links.persons_with_significant_control_statements_list
optional
StringThe URL of the persons with significant control statements list resource.
links.selfStringThe URL of the resource.
start_indexIntegerThe offset into the entire result set that this page starts.

total_results
optional

IntegerThe total number of officers in this result set.

PersonWithSignificantControl 

Name
Type
Description

address

AddressThe correspondence address of the officer.
ceased_onDateThe date that Companies House was notified about the cessation of this person with significant control.
country_of_residence
optional
StringThe officer's country of residence.
date_of_birth
optional
Date of birthDetails of director date of birth.

etag

StringThe ETag of the resource.
linksObjectA set of URLs related to the resource, including self.
links.selfObjectThe URL of the resource.
links.statement
optional
StringThe URL of the statement linked to this person with significant control.
nameStringName of the person with significant control.

name_elements
optional
mandatory for an individual person with significant control

Name ElementsA document encapsulating the seperate elements of a person with significant control's name.
nationality
optional
StringThe officer's nationality.
natures_of_control
optional
ArrayIndicates the nature of control the person with significant control holds. 
For enumeration descriptions see description section in the enumeration mappings file.
notified_onDateThe date that Companies House was notified about this person with significant control.

Name Elements 

Name
Type
Description

forename

StringThe forename of the person with significant control.
other_forenamesStringOther forenames of the person with significant control.
surnameStringThe surname of the person with significant control.
titleStringTitle of the person with significant control.

Filing History List 

Name
Type
Description

etag

StringThe ETag of the resource.

filing_history_status
optional

StringThe status of this filing history. Possible values are:
  • filing-history-available
itemsList<Filing History>The filing history items
items_per_pageIntegerThe number of filing history items returned per page.
kindStringIndicates this resource is a filing history. Possible values are:
  • filing-history
start_indexIntegerThe index into the entire result set that this result page starts.
total_countIntegerThe total number of filing history items for this company.

Filing History 

Name
Type
Description

annotations
optional

List<Annotation>Annotations for the filing

associated_filings
optional

List<Associated Filing>Any filings associated with the current item

barcode
optional

StringThe barcode of the document.

category
optional

StringThe category of the document filed. Possible values are:
  • accounts
  • address
  • annual-return
  • capital
  • change-of-name
  • incorporation
  • liquidation
  • miscellaneous
  • mortgage
  • officers
  • resolution
dateDateThe date the filing was processed.
descriptionStringA description of the filing. 
For enumeration descriptions see description section in the enumeration mappings.

links
optional

ObjectLinks to other resources associated with this filing history item.
links.document_metadata
optional
StringLink to the document metadata associated with this filing history item. See the Document API documentation for more details.
links.self
optional
StringLink to this filing history item.
pages
optional
IntegerNumber of pages within the PDF document (links.document_metadata)
paper_filed
optional
BooleanIf true, indicates this is a paper filing.
resolutions
optional
List<Resolution>Resolutions for the filing
subcategory
optional
StringThe sub-category of the document filed. Possible values are:
  • resolution
transaction_idStringThe transaction ID of the filing.
typeStringThe type of filing.
items_per_pageIntegerThe number of filing history items returned per page.

kind

StringIndicates this resource is a filing history. Possible values are:
  • filing-history
start_indexIntegerThe index into the entire result set that this result page starts.
total_countIntegerThe total number of filing history items for this company.

Annotation 

Name
Type
Description

annotation
optional

StringThe annotation text.

date

DateThe date the annotation was added.

description

StringA description of the annotation. 
For enumeration descriptions see description section in the enumeration mappings.

Associated Filing  

Name
Type
Description

date

DateThe date the associated filing was processed.
descriptionStringA description of the associated filing. 
For enumeration descriptions see description section in the enumeration mappings.
typeStringThe type of the associated filing.

Resolution  

Name
Type
Description

category

DateThe date the associated filing was processed.
descriptionStringA description of the associated filing. 
For enumeration descriptions see description section in the enumeration mappings.
document_id
optional
StringThe document id of the resolution.
receive_dateDateThe date the resolution was processed.
subcategoryStringThe sub-category of the document filed. Possible values are:
  • resolution
typeStringThe type of the associated filing.

 MS Face API

Overview

The Microsoft Face API provides the functionality of determining the likelihood of two facial images belonging to the same person. The API will
return a conclusion along with a confidence score that can be used to decide if the match is successful or not. Determining the proper confidence
threshold for an application is typically subject to tuning as it will depend on image quality as well as the required strictness for the application.

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.

API

PathVerbContent typeInputOutput
/ms-face/detectPOSTapplication/octet-streamBinary image file, max file size 4 MBIf successful (HTTP 200), returns DetectResponse.
/ms-face/verifyPOSTapplication/jsonVerifyRequestVerifyResponse

 

Code examples

Example using cURL
Example using cURL
Example using Java

Messages

DetectResponse

NameTypeDescription
FaceIdUUIDA unique identifier for the face detected in the image
FaceRectangleFaceRectangleCoordinates for the face location in the image

FaceRectangle

NameTypeDescription
TopIntThe y-coordinate for the bounding rectangle
LeftIntThe x-coordinate for the bounding rectangle
WidthIntThe width of the bounding rectangle
HeightIntThe height of the bounding rectangle

VerifyRequest

NameTypeDescription
FaceId1UUIDThe first unique identifier of a detected face, as returned by the DetectResponse.
FaceId2UUIDThe second unique identifier of a detected face, as returned by the DetectResponse.

VerifyResponse

NameTypeDescription
IsIdenticalBooleanTrue if the two faces are determined to belong to the same person.
ConfidenceDecimalA confidence score for the IsIdentical determination.

 


 Trapets API

Overview

Trapets enables screening of customers against sanctions, Ofac and PEP lists for KYC purposes. Please refer to the Trapets KYC product sheet f
or 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

PathVerbContent TypeInputOutput
/trapets/queryPOSTapplication/jsonDoQueryList<QueryResult>


Code examples

Example request using cURL
Example response
Example using Java

Messages

DoQuery

NameTypeDescription
ServiceNameString

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".

QueryAttributesList<QueryAttribute>List of query attributes.

QueryAttribute

NameTypeDescription
AttributeIdStringThe id of the QueryAttribute, used for reference in order to be able to map an array of responses to the request set.

Country
optional

List<Country>

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).

NameString

The name of the subject being queried. “Anders Andersson”. The order of the names does not matter. Some phonetic
interpretation is made. The more parts of a name being submitted the more the search is narrowed.

BirthDate
optional

String

The birth date in the format of “yyyyMMdd”. If omitted no filtering on birthdate is made for this QueryAttribute. Items in
the KYC database that does not have a birth date set will not be filtered out.

Ssn
optional

String

The ssn (social security number) is generally entered in the format that is used by the issuing country with the two letter
iso country code as prefix. Any hyphens or such characters omitted. Below is an example of a Swedish ssn:
SE195707210190.

Country

NameTypeDescription
IdIntThe internal Id of the country. Only used as a reference.
NameStringThe name of the country in English.
TwoLetterString

The ISO 31661 alpha2 code of the country.

ThreeLetterString

The ISO 31661 alpha2 code of the country.

 

QueryResult

NameTypeDescription
AttributeIdStringThe Id of the QueryAttribute. It will be identical to the value passed in the DoQuery method.
Countries

List<Country>

A list of countries matching the QueryAttribute. If this array contains any elements it means the country supplied is
on a sanction list itself.

EntitiesList<Entity>

A list of entities matching the QueryAttribute.

Individuals

List<Individual>

A list of individuals matching the QueryAttribute.

NameStringThe name of the result. Usually made up of the names in the QueryAttribute.

 

Individual

NameTypeDescription
IdIntThe internal Id. Only used as a reference.
AttributeIdString The Id of the QueryAttribute. It will be identical to the value passed in DoQuery.
ExternalIdString 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.
LastUpdateDatetime 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”.
UrlStringURL to the source document.
Comment StringA comment on this entry if any.

Xml

String An 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.
ExternalURLsStringA 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.
TitleStringThe title of the individual, ex: General.
FunctionDescription StringThe 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” member will be
null and this value might be set.
ItemNumber String The Ssn of the individual in the issuing country’s format.

HitRating

IntIndicates how relevant this listitem is to the query. The higher number, the more accurate, with 5 being the
most accurate:
Ssn => 5
BirthDate => 4
Year (Birthdate) => 2
Name => 1

Entity

NameTypeDescription
IdIntThe internal Id. Only used as a reference.
AttributeIdStringThe 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.
PostDateDatetime 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”.
UrlStringURL to the source document.
Comment String A comment on this entry if any.
Xml String An 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 of the individual in the issuing country’s format.

HitRating

Int 

 

 

  • No labels