Know Your Business Methods | Sanction Scanner Developer Portal

Scan Companies

Required input informations of ScanCompanies Restful Service should be prepared in RESTful (JSON) format and sent the following address with GET method.
api/Kyb/ScanCompanies

Purpose: Searches for companies using fuzzy matching. It finds companies based on specific criteria and sorts the results by match rate.

Token Informations

Parameter Name	Data Type	Requirement	Description
username	String	Yes	Api Username Info
password	String	Yes	Api Password Info

Input Parameters

Parameter Name	Data Type	Requirement	Default	Description
searchTerm	String	Yes	-	Company name or search term (minimum 3 characters) - query parameter
start	Integer	No	0	Starting index for pagination - query parameter
limit	Integer	No	20	Maximum number of results - Limited to a maximum of 50 - query parameter
matchRate	Integer	No	80	Minimum fuzzy match rate percentage - query parameter
status	String	No	null	Company status filter (e.g., "Active", "Dissolved") - query parameter
startDate	DateTime	No	null	Start date for filtering - query parameter
endDate	DateTime	No	null	End date for filtering - query parameter
listTypeId	String	No	null	List type ID filter (e.g., "1", "2,3"). If not provided, searches all lists - query parameter

Response Fields

Field Name	Data Type	Description
Success	Boolean	True if the request was successful
SearchTerm	String	The search term used
MatchRate	Integer	The match rate used for the search
Data	Array (String)	Array of company objects containing matching companies
TotalCount	Long	Total number of records found
Start	Integer	Pagination starting index
Limit	Integer	Maximum number of records displayed per page
ResultsFound	Integer	Number of companies found in the current response
Message	String	Informative message about the search result

Data Array Fields

Field Name	Data Type	Description
Id	Integer	Unique ID of the company in the database
CompanyNumber	String	Company registration number
CompanyName	String	Company name
CompanyStatusId	Integer	ID of the company status
ListTypeId	Integer	ID of the list type the company belongs to

Example Successful Response:

{
  "Success": true,
  "SearchTerm": "sanction scanner",
  "MatchRate": 80,
  "Data": [
    {
      "Id": 101,
      "CompanyNumber": "UK12345678",
      "CompanyName": "Sanction Scanner Technologies Ltd.",
      "CompanyStatusId": 1,
      "ListTypeId": 3
    },
    {
      "Id": 102,
      "CompanyNumber": "US87654321",
      "CompanyName": "Sanction Scanner Inc.",
      "CompanyStatusId": 1,
      "ListTypeId": 7
    },
    {
      "Id": 103,
      "CompanyNumber": "TR11223344",
      "CompanyName": "Sanction Scanner Turkey Ltd.",
      "CompanyStatusId": 1,
      "ListTypeId": 8
    }
  ],
  "TotalCount": 3,
  "Start": 0,
  "Limit": 20,
  "ResultsFound": 3,
  "Message": "Found 3 companies matching 'sanction scanner' with 80%+ similarity"
}

Error Responses:
HTTP 400 Bad Request: Search term must be at least 3 characters long / Search query errors
HTTP 401 Unauthorized: Invalid authentication credentials
HTTP 500 Internal Server Error: System Error

Company Check

Required input informations of CompanyCheck Restful Service should be prepared in RESTful (JSON) format and sent the following address with GET method.
api/Kyb/CompanyCheck

Purpose: Performs a company check using the specified company number and returns simplified company details. This operation also creates a new KYBSearchLog record.

Token Informations

Parameter Name	Data Type	Requirement	Description
username	String	Yes	Api Username Info
password	String	Yes	Api Password Info

Input Parameters

Parameter Name	Data Type	Requirement	Description
companyNumber	String	Yes	The company number to be checked (query parameter)
referenceNumber	String	No	Reference number for the search (query parameter). If not provided, a GUID is automatically generated

Response Fields

Field Name	Data Type	Description
ScanId	String	Unique identifier for the scan operation (e.g., "K000002")
ReferenceNumber	String	Reference number specified by the user or automatically generated
SearchTerm	String	Company name or term used in the search
ScanDate	String	Date when the scan operation was performed (YYYY-MM-DD format)
Searcher	String	Username of the user who performed the search
AssignedUser	String	User assigned to review this case (null for new company checks)
MatchStatusId	int	Match Status Id of scan (null for new company checks)
RiskLevelId	int	Risk Level Id of scan (null for new company checks)
Tags	String	Comma-separated list of tags (null for new company checks)
TagValues	Array (String)	Array of tag objects (empty for new company checks)
CompanyData	Object	Profile object containing general profile information of the company
CompanyOfficer	Object	Officer object containing company officer information
CompanyRegistry	Object	Company registry information with registrar details
CompanyDetailInfo	Object	Company detail information with registration records

Example Successful Response:

{
  "ScanId": "K000002",
  "ReferenceNumber": "REF-SS-CHECK-002",
  "SearchTerm": "Sanction Scanner",
  "ScanDate": "2024-10-26",
  "Searcher": "api-user",
  "AssignedUser": null,
  "MatchStatusId": null,
  "RiskLevelId": null,
  "value": "Sanction Scanner",
  "Tags": null,
  "TagValues": [],
  "CompanyData": {
    "Result": [
      {
        "CompanyName": "Sanction Scanner Technologies Ltd.",
        "CompanyNumber": "UK12345678",
        "CompanyStatus": "Active",
        "DateOfCreation": "2018-05-15",
        "RegisteredOfficeAddress": {
          "address_line_1": "London Office, 123 Tech Street",
          "locality": "London",
          "postal_code": "EC1A 1BB",
          "country": "GB",
          "region": "England"
        },
        "MatchRate": 98,
        "WhiteListMessage": null,
        "SafeListId": null
      }
    ]
  },
  "CompanyOfficer": {
    "items": [
      {
        "name": "John Smith",
        "officer_role": "Director",
        "appointed_on": "2018-05-15",
        "nationality": "British",
        "country_of_residence": "United Kingdom",
        "address": {
          "address_line_1": "Director Address, 456 Business Ave",
          "locality": "London",
          "postal_code": "EC1A 2BB",
          "country": "United Kingdom"
        },
        "date_of_birth": {
          "year": 1985,
          "month": 8
        }
      }
    ]
  },
  "CompanyRegistry": {
    "RegisteredOffice": "London Office Address",
    "Registrar": "Companies House",
    "RegisterNummer": "12345678",
    "RegisterNummerSuffix": null,
    "FormerRegistrar": null,
    "RegisterFlag": "Active",
    "RegisterFlagNote": null,
    "RegistrarFlagStatusInfo": "Current registration",
    "DecodedRegisteredOffice": "London Office Address",
    "DecodedRegistrar": "Companies House"
  },
  "CompanyDetailInfo": {
    "Registrations": [
      {
        "Id": 1,
        "Confidence": 0.98,
        "RegistrationDataTypeId": 1,
        "PublicationDate": "2018-05-15",
        "RetrievedAt": "2024-10-26",
        "SourceUrl": "https://find-and-update.company-information.service.gov.uk/",
        "StartDate": "2018-05-15",
        "StartDateType": 1,
        "SubsequentRegistrationStartDate": null,
        "PreviousCompanyNumber": null,
        "SubsequentCompanyNumber": null,
        "SampleDate": "2024-10-26",
        "AlternateCompanyNumber": null,
        "PreviousRegistrationEndDate": null
      }
    ]
  }
}

Error Responses:
HTTP 401 Unauthorized: Invalid authentication credentials
Internal Error Handling: The method returns null in case of errors (Company number is required / Company not found in database)
System Error: Returns empty response object in case of CompanyCheck API errors

Get Detail Reference Number

Required input informations of GetCompanyDetailByReferenceNumber Restful Service should be prepared in RESTful (JSON) format and sent the following address with GET method.
api/Kyb/GetCompanyDetailByReferenceNumber

Purpose: Retrieves detailed company information by reference number. This is used to get the details of a previously performed company check.

Token Informations

Parameter Name	Data Type	Requirement	Description
username	String	Yes	Api Username Info
password	String	Yes	Api Password Info

Input Parameters

Parameter Name	Data Type	Requirement	Description
referenceNumber	String	Yes	The reference number of the company search (query parameter)

Response Fields

Field Name	Data Type	Description
ScanId	String	Unique identifier for the scan operation (e.g., "K000001")
ReferenceNumber	String	Reference number specified by the user or automatically generated
SearchTerm	String	Company name or term used in the search
ScanDate	String	Date when the scan operation was performed (YYYY-MM-DD format)
Searcher	String	Username of the user who performed the search
AssignedUser	String	Full name of the user assigned to the relevant case
MatchStatusId	int	Match Status Id of scan 0:Unknown 1:No Match 2:Potential Match 3:False Positive 4:True Positive 5:True Positive Approve 6:True Positive Reject
RiskLevelId	int	Risk Level Id of scan 0:Unknown 1:Low 2:Medium 3:High 4:Neutral 5:Increased 6:Unacceptable
Tags	String	Comma-separated list of tags associated with the company
TagValues	Array (String)	Array of tag objects with TagId and Value properties
CompanyData	Object	Profile object containing general profile information of the company
CompanyOfficer	Object	Officer object containing company officer information
CompanyRegistry	Object	Company registry information with registrar details
CompanyDetailInfo	Object	KybCompanyDetailInfo containing detailed company information

Example Successful Response:

{
  "ScanId": "K000001",
  "ReferenceNumber": "REF-SS-001",
  "SearchTerm": "Sanction Scanner",
  "ScanDate": "2024-10-26",
  "Searcher": "api-user",
  "AssignedUser": "Compliance Officer",
  "MatchStatusId": 4,
  "RiskLevelId": 1,
  "value": "Sanction Scanner",
  "Tags": "Technology, FinTech",
  "TagValues": [
    {
      "TagId": 1,
      "Value": "Technology"
    },
    {
      "TagId": 2,
      "Value": "FinTech"
    }
  ],
  "CompanyData": {
    "Result": [
      {
        "CompanyName": "Sanction Scanner Technologies Ltd.",
        "CompanyNumber": "UK12345678",
        "CompanyStatus": "Active",
        "DateOfCreation": "2018-05-15",
        "RegisteredOfficeAddress": {
          "address_line_1": "London Office, 123 Tech Street",
          "locality": "London",
          "postal_code": "EC1A 1BB",
          "country": "GB",
          "region": "England"
        },
        "MatchRate": 98,
        "WhiteListMessage": null,
        "SafeListId": null
      }
    ]
  },
  "CompanyOfficer": {
    "items": [
      {
        "name": "John Smith",
        "officer_role": "Director",
        "appointed_on": "2018-05-15",
        "nationality": "British",
        "country_of_residence": "United Kingdom",
        "address": {
          "address_line_1": "Director Address, 456 Business Ave",
          "locality": "London",
          "postal_code": "EC1A 2BB",
          "country": "United Kingdom"
        },
        "date_of_birth": {
          "year": 1985,
          "month": 8
        }
      }
    ]
  }
}

Error Responses:
HTTP 400 Bad Request: Reference number is required / Error parsing company data
HTTP 401 Unauthorized: Invalid authentication credentials
HTTP 404 Not Found: No checked company record found for this reference number
HTTP 500 Internal Server Error: System Error

Response Field Details

Main Response Object Fields

Field Name	Data Type	Description
Id	Integer	Unique identifier for the response record
ScanId	String	Formatted scan identifier (e.g., "K000350")
ReferenceNumber	String	Reference number for tracking the search
SearchTerm	String	Original search term used
ScanDate	String	Date when the scan was performed (YYYY-MM-DD format)
Searcher	String	Username of the person who performed the search
AssignedUser	String	User assigned to review this case (GetCompanyDetailByReferenceNumber only)
MatchStatus	String	Current status of the match review (GetCompanyDetailByReferenceNumber only)
RiskLevel	String	Risk assessment level (GetCompanyDetailByReferenceNumber only)
Tags	String	Comma-separated list of tags assigned to this case
Memo	String	Notes or memos associated with this case
Company	Object	Detailed company information object containing registration details
CompanyRegistries	Array	Array of company registry information from different registrars
Registrations	Array	Array of registration records with confidence levels and source URLs
Officers	Array	Array of company officers and directors with their details

Company Object Fields

Field Name	Data Type	Description
Id	Integer	Unique company identifier
CompanyNumber	String	Official company registration number
Name	String	Official company name
TaxNumber	String	Tax identification number
TaxOffice	String	Tax office responsible for the company
RegisteredAddress	String	Official registered address
EstablishmentDate	DateTime	Date when the company was established (YYYY-MM-DD format)
DeregistrationDate	DateTime	Date when the company was deregistered (YYYY-MM-DD format, null if active)
FederalState	String	Federal state or region where company is registered
NativeCompanyNumber	String	Local/native company number format
TotalCapital	Decimal	Total capital amount
Currency	String	Currency of the capital (ISO code)
ElectronicNotificationAddress	String	Electronic notification email address
CreatedDate	DateTime	When this record was created in the system
ModifiedDate	DateTime	When this record was last modified

Officers Object Fields

Field Name	Data Type	Description
Id	Integer	Unique officer record identifier
CompanyId	Integer	Reference to the company
IdentificationNumber	String	Official identification number
PassportNumber	String	Passport number if available
TaxNumber	String	Tax identification number
Name	String	Full name of the officer
OfficerPositionId	Integer	Reference to position type (Director, Secretary, etc.)
StartDate	DateTime	Date when the officer started in this position (YYYY-MM-DD format)
City	String	City where the officer resides
FirstName	String	First name
LastName	String	Last name
Title	String	Official title/position description
BirthDate	DateTime	Date of birth
Nationality	String	Nationality
CountryOfResidence	String	Country where the officer resides
Dismissed	Boolean	Whether the officer has been dismissed
EndDate	DateTime	Date when the officer left the position (YYYY-MM-DD format)
MaidenName	String	Maiden name if applicable
Address	String	Residential address
ReferenceNo	Integer	Internal reference number
CreatedDate	DateTime	When this officer record was created
ModifiedDate	DateTime	When this officer record was last modified

Reference Data

Company Status Types

Status ID	Status Name	Description
1	Registered	Company is currently registered and active
2	Removed	Company has been removed from the register
3	Unchanged	No changes to company status
4	Resumed Activity after Temporary Cessation	Company has resumed operations
5	Active	Company is actively operating
6	In Liquidation	Company is in the process of liquidation
7	Active - Proposal to Strike off	Active company with strike-off proposal
8	In Administration	Company is under administration
9	Voluntary Arrangement (CVA)	Company has a voluntary arrangement
10	In Administration / Receiver Manager	Under administration with receiver
11	Receivership	Company is in receivership
12	CVA and Receiver Manager	Both CVA and receiver manager
13	Administration with Receiver Manager	Administration with receiver manager
14	Administrative Receiver	Under administrative receivership
15	Modified	Company details have been modified
16	CVA under Admin Receivership	CVA under administrative receivership
17	Bankrupt	Company is bankrupt

List Types (Countries)

List ID	List Name	Country ISO Code	Description
1	Germany	DE	German company registry data
2	France	FR	French company registry data
3	United Kingdom	GB	UK company registry data
4	Estonia	EE	Estonian company registry data
5	Switzerland	CH	Swiss company registry data
6	Slovakia	SK	Slovak company registry data