NameScan API Reference v3

Welcome to the NameScan RESTful API. You can use our API to access NameScan functionalities.

The NameScan API is organised around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, such as HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors.

We have language bindings in cUrl, Ruby, Python and Java. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Old API References

This document is related to API 3.0. You can find old version documents if you use previous versions.

NameScan API Reference v2

Authentication

Authenticate your account when using the API by including your secret or test API key in the request. You can manage your API keys in your profile. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas.

NameScan API expects for the API key to be included in all API requests to the server in a header that looks like the following:

api-key: your-api-key

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

NameScan uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted, etc) and codes in the 5xx range indicate an error with NameScans servers.

Error Codes

Status	Description
200 - OK	The request succeeded and the requested information is in the response. This is the most common status code to receive.
201 - Created	The request resulted in a new resource being created before the response was sent.
204 - No Content	The request has been successfully processed and the response is intentionally blank.
400 - Bad Request	The request could not be understood by the server. Bad Request is sent when no other error is applicable, if the exact error is unknown or does not have its own error code.
401 - Unauthorized	The requested resource requires authentication.
403 - Forbidden	The server refuses to fulfill the request.
500 - Internal Server Error	A generic error has occurred on the server.

In addition to the error code, the response always contains a message that describes the details of the error that occurred.

The “400 - Bad Request” response also always contains a ModelState that describes detail of incorrect or invalid sent parameter.

Emerald Scans

The Emerald scan API’s allow you to perform new person scan, perform new organisation scan and get sanction lists information. The monthly history is available via scan history API.

New Person Emerald Scan

Code samples

# You can also use wget
curl -X post https://api.namescan.io/v3/person-scans/emerald \
     -H "api-key: your-api-key" \
     -H "content-type: application/json" \
     -d "{'firstName':'john', 'lastName':'smith', 'dob':'1970', 'listType':'sanction' }"

POST https://api.namescan.io/v3/person-scans/emerald HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/person-scans/emerald',
    method: 'post',
    headers: {'api-key': 'your-api-key'},
    data: {'name': 'john smith'},
    success: function(result) {
      console.log(JSON.stringify(result));
    }
  })
</script>

const request = require('node-fetch');
var data = {name: 'john smith'};
fetch('https://api.namescan.io/v3/person-scans/emerald', {
    method: 'POST',
    headers: {'api-key': 'your-api-key', 'Content-Type': 'application/json'},
    body: JSON.stringify(data)
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.post 'https://api.namescan.io/v3/person-scans/emerald', ...

    # TODO

p = JSON.parse(result)

import requests

header = {'api-key': 'your-api-key', 'Content-Type': 'application/json'}
data = {'name': 'john smith'}
r = requests.post('https://api.namescan.io/v3/person-scans/emerald',
    headers = header, json = data)

print r.json()

URL obj = new URL("https://api.namescan.io/v3/person-scans/emerald");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("api-key", "your api key");
con.setRequestProperty("Content-Type", "application/json");

con.setDoInput(true);
con.setDoOutput(true);

DataOutputStream output = new DataOutputStream(con.getOutputStream());
String data = "{\"name\":\"John Smith\"}";
output.writeBytes(data);
output.flush();
output.close();

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /v3/person-scans/emerald

Performs new person Emerald scan

Allows you to scan persons on Emerald lists by entering their information into the fields provided.

Parameters

Parameter	In	Type	Required	Description
param	body	personScanEmeraldParam	true	Person scan parameter, which includes person information to find. name or firstName/lastName is required. name can be full name or original script. original script is a name in any Non-Latin/Roman based language, such as Cyrillic, Arabic, Hebrew, Chinese, etc... When both firstName/lastName and name are entered and name is Latin/Roman, the name is ignored and only firstName/lastName are scanned but, when the name is original script (Non-Latin/Roman) the result includes profiles matched with firstName/lastName or original script. gender can be male, female or empty. dob can be in dd/mm/yyyy or yyyy formats. listType can be pep or sanction. leave listType as empty to scan on all lists. use includedLists if you want to scan only over a specified sanction lists. use includedLists if you wish to scan against only specific sanction lists. If you wish to exclude particular sanction lists from your scan use excludedLists. Only one of the two lists can have a value and their value should be a comma separated id. Eg: UN, SDN etc. matchRate is a percentage from 1-100, which indicates how closely the name being checked matches the name on the matching watchlist profile, with 1% being not close and 100% being very close. When the entered name is in original script, match rate is calculated based on the number of matched parts. If you enter the optional fields dob, country or gender and they do not match the Emerald database, the match rate will be reduced by 40%, 50% or 60% respectively.

Body parameter

{
  "name": "string",
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "gender": "string",
  "dob": "string",
  "country": "string",
  "listType": "string"
  "includedLists": "string"
  "excludedLists": "string"
  "matchRate": 0
}

Responses

Status	Meaning	Description
201	Created	personScanEmeraldResult: contains information of matched persons.
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure

{
  "date": "2017-07-29T12:06:08Z",
  "scanId": "string",
  "numberOfMatches": 0,
  "persons": [
    {
      "uid": "string",
      "updateAt": "string",
      "updateInfo": "string",
      "category": "string",
      "deceased": true,
      "deceasedDate": "string",
      "name": "string",
      "title": "string",
      "firstName": "string",
      "middleName": "string",
      "lastName": "string",
      "gender": "string",
      "originalScriptName": "string",
      "sortKeyName": "string",
      "datesOfBirth": [
        {
          "date": "string",
          "note": "string"
        }
      ],
      "placesOfBirth": [
        {
          "city": "string",
          "region": "string",
          "country": "string",
          "text": "string",
          "note": "string",
          "type": "string"
        }
      ],
      "referenceType": "string",
      "references": [
        {
          "name": "string",
          "since": "string",
          "to": "string",
          "idInList": "string"
        }
      ],
      "program": "string",
      "nationality": "string",
      "citizenship": "string",
      "addresses": [
        {
          "address1": "string",
          "address2": "string",
          "address3": "string",
          "city": "string",
          "region": "string",
          "postalCode": "string",
          "country": "string",
          "text": "string",
          "note": "string"
        }
      ],
      "places": [
        {
          "country": "string",
          "type": "string"
        }
      ],
      "otherNames": [
        {
          "title": "string",
          "name": "string",
          "firstName": "string",
          "middleName": "string",
          "lastName": "string",
          "type": "string"
        }
      ],
      "roles": [
        {
          "title": "string",
          "category": "string",
          "since": "string",
          "to": "string",
          "type": "string"
        }
      ],
      "occupations": [
        "string"
      ],
      "father": "string",
      "mother": "string",
      "spouse": "string",
      "children": [
        "string"
      ],
      "siblings": [
        "string"
      ],
      "identities": [
        {
          "number": "string",
          "country": "string",
          "note": "string",
          "type": "string"
        }
      ],
      "contacts": [
        {
          "value": "string",
          "type": "string"
        }
      ],
      "images": [
        "string"
      ],
      "links": [
        {
          "url": "string",
          "type": "string"
        }
      ],
      "sources": [
        "string"
      ],
      "basis": "string",
      "summary": "string",
      "matchRate": 0
    }
  ]
}

New Organisation Emerald Scans

Code samples

# You can also use wget
curl -X post https://api.namescan.io/v3/organisation-scans/emerald \
     -H "api-key: your-api-key" \
     -H "content-type: application/json" \
     -d "{'name':'al-shabab' }"

POST https://api.namescan.io/v3/organisation-scans/emerald HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/organisation-scans/emerald',
    method: 'post',
    headers: {'api-key': 'your-api-key'},
    data: {'name': 'al-shabab'},
    success: function(result) {
      console.log(JSON.stringify(result));
    }
  })
</script>

const request = require('node-fetch');
var data = {name: 'al-shabab'};
fetch('https://api.namescan.io/v3/organisation-scans/emerald', {
    method: 'POST',
    headers: {'api-key': 'your-api-key', 'Content-Type': 'application/json'},
    body: JSON.stringify(data)
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.post 'https://api.namescan.io/v3/organisation-scans/emerald', ...

    # TODO

p = JSON.parse(result)

import requests

header = {'api-key': 'your-api-key', 'Content-Type': 'application/json'}
data = {'name': 'al-shabab'}
r = requests.post('https://api.namescan.io/v3/organisation-scans/emerald',
    headers = header, json = data)

print r.json()

URL obj = new URL("https://api.namescan.io/v3/organisation-scans/emerald");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("api-key", "your api key");
con.setRequestProperty("Content-Type", "application/json");

con.setDoInput(true);
con.setDoOutput(true);

DataOutputStream output = new DataOutputStream(con.getOutputStream());
String data = "{\"name\":\"al-shabab\"}";
output.writeBytes(data);
output.flush();
output.close();

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /v3/organisation-scans/emerald

Performs new organisation Emerald scan

Allows you to scan organisations on Emerald lists by entering their information into the fields provided.

Parameters

Parameter	In	Type	Required	Description
param	body	organisationScanEmeraldParam	true	Organisation scan parameter, which includes organisation information to find. name is required and can be original script. use includedLists if you want to scan only over a specified sanction lists. use includedLists if you wish to scan against only specific sanction lists. If you wish to exclude particular sanction lists from your scan use excludedLists. Only one of the two lists can have a value and their value should be a comma separated id. Eg: UN, SDN etc. matchRate is a percentage from 1-100, which indicates how closely the name being checked matches the name on the matching watchlist profile, with 1% being not close and 100% being very close. If you enter the optional field country and it does not match the Emerald database, the match rate will be reduced by 50%.

Body parameter

{
  "name": "string",
  "country": "string",
  "includedLists": "string"
  "excludedLists": "string"
  "matchRate": 0
}

Responses

Status	Meaning	Description
201	Created	organisationScanEmeraldResult: contains information of matched organisations.
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure

{
  "date": "2017-07-29T12:06:08Z",
  "scanId": "string",
  "numberOfMatches": 0,
  "organisations": [
    {
      "uid": "string",
      "updateAt": "string",
      "updateInfo": "string",
      "category": "string",
      "name": "string",
      "originalScriptName": "string",
      "sortKeyName": "string",
      "referenceType": "string",
      "references": [
        {
          "name": "string",
          "since": "string",
          "to": "string",
          "idInList": "string"
        }
      ],
      "program": "string",
      "addresses": [
        {
          "address1": "string",
          "address2": "string",
          "address3": "string",
          "city": "string",
          "region": "string",
          "postalCode": "string",
          "country": "string",
          "text": "string",
          "note": "string"
        }
      ],
      "otherNames": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "identities": [
        {
          "number": "string",
          "country": "string",
          "note": "string",
          "type": "string"
        }
      ],
      "contacts": [
        {
          "value": "string",
          "type": "string"
        }
      ],
      "images": [
        "string"
      ],
      "links": [
        {
          "url": "string",
          "type": "string"
        }
      ],
      "sources": [
        "string"
      ],
      "basis": "string",
      "summary": "string",
      "matchRate": 0
    }
  ]
}

Get Sanction Lists Information

Code samples

# You can also use wget
curl -X get https://api.namescan.io/v3/lists/emerald/sanctions \
     -H "api-key: your-api-key"

GET https://api.namescan.io/v3/lists/emerald/sanctions HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/lists/emerald/sanctions',
    method: 'get',
    headers: {'api-key': 'your-api-key'},
    success: function(data) {
      console.log(JSON.stringify(data));
    }
  })
</script>

const request = require('node-fetch');
fetch('https://api.namescan.io/v3/lists/emerald/sanctions', {
    method: 'GET',
    headers: {'api-key': 'your-api-key'}
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.namescan.io/v3/lists/emerald/sanctions', ...

    # TODO

p = JSON.parse(result)

import requests

header = {'api-key': 'your-api-key'}
param = {'scan_id': 'your-scan-id'}
r = requests.get('https://api.namescan.io/v3/lists/emerald/sanctions',
    headers = header, params = param)

print r.json()

URL obj = new URL("https://api.namescan.io/v3/lists/emerald/sanctions");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("api-key", "your api key");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /v3/lists/emerald/sanctions

Retrieve sanction lists information

Allows you to retrieve information of sanction lists. The list ID can be used on the included or the excluded list parameter of a person or organisation scan.

Responses

Status	Meaning	Description
200	OK	listInfo: contains id and name of sanction list.
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure

[
  {
    "id": "string",
    "name": "string"
  }
]

Sapphire Scans

The Sapphire scan API’s allow you to perform new person scan an perform new organisation scan. The monthly history is available via scan history API.

New Person Sapphire Scan

Code samples

# You can also use wget
curl -X post https://api.namescan.io/v3/person-scans/sapphire \
     -H "api-key: your-api-key" \
     -H "content-type: application/json" \
     -d "{'firstName':'john', 'lastName':'smith', 'dob':'21/10/1970' }"

POST https://api.namescan.io/v3/person-scans/sapphire  HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/person-scans/sapphire',
    method: 'post',
    headers: {'api-key': 'your-api-key'},
    data: {'firstName':'john', 'lastName':'smith'},
    success: function(result) {
      console.log(JSON.stringify(result));
    }
  })
</script>

const request = require('node-fetch');
var data = {firstName: 'john', lastName: 'smith'};
fetch('https://api.namescan.io/v3/person-scans/sapphire', {
    method: 'POST',
    headers: {'api-key': 'your-api-key', 'Content-Type': 'application/json'},
    body: JSON.stringify(data)
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.post 'https://api.namescan.io/v3/person-scans/sapphire', ...

    # TODO

p = JSON.parse(result)

import requests

header = {'api-key': 'your-api-key', 'Content-Type': 'application/json'}
data = {'firstName':'john', 'lastName':'smith'}
r = requests.post('https://api.namescan.io/v3/person-scans/sapphire',
    headers = header, json = data)

print r.json()

URL obj = new URL("https://api.namescan.io/v3/person-scans/sapphire");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("api-key", "your api key");
con.setRequestProperty("Content-Type", "application/json");

con.setDoInput(true);
con.setDoOutput(true);

DataOutputStream output = new DataOutputStream(con.getOutputStream());
String data = "{\"firstName\":\"John\";\"lastName\":\"Smith\"}";
output.writeBytes(data);
output.flush();
output.close();

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /v3/person-scans/sapphire

Performs new person Sapphire scan

Allows you to scan persons on Sapphire lists by entering their information into the fields provided.

Parameters

Parameter	In	Type	Required	Description
param	body	personScanSapphirParam	true	Person scan parameter, which includes person information to find. firstName/lastName or originalName is required. middleName is optional. For each record, you can choose to check firstName and lastName or originalName or both firstName and lastName and originalName. originalName can either be the person's full name in Non-Latin/Roman based language (e.g. Cyrillic, Arabic, Chinese etc) or the full Latin-based name if you are unable to separate based on First, Middle and Last Name. gender can be male, female or empty. dob can be date in dd/mm/yyyy or yyyy format. matchRate is a percentage from 1-100, which indicates how closely the name being checked matches the name on the matching watchlist profile, with 1% being not close and 100% being very close. If you enter the optional fields dob, country or gender and they do not match the Sapphire database, the found entity will be removed from the results. maxResultCount indicates the maximum number of matches that should be returned. It must be between 1 and 200; defaults to 100.

Body parameter

{
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "originalName": "string"
  "gender": "string",
  "dob": "string",
  "country": "string",
  "matchRate": 75,
  "maxResultCount": 100
}

Responses

Status	Meaning	Description
201	Created	personScanSapphireResult: contains information of matched persons.
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure

{
  "date": "2017-07-29T12:06:08Z",
  "scanId": "string",
  "numberOfMatches": 0,
  "persons": [
    {
      "uid": "string",
      "category": "string",
      "matchRate": 0,
      "resultId": "string",
      "flag": 0,
      "person": 
         {
            "uniqueId": "string",
            "categories": "string",
            "subcategory": "string",
            "gender": "string",
            "deceased": "string",
            "primaryFirstName": "string",
            "primaryMiddleName": "string",
            "primaryLastName": "string",
            "title": "string",
            "image": "string",
            "position": "string",
            "dateOfBirth": "string",
            "deceasedDate": "string",
            "placeOfBirth": "string",
            "primaryLocation": "string",
            "generalInfo": 
              {
                "nationality": "string",
                "alternateTitle": "string",
                "businessDescription": "string",
                "website": "string",
              }
            "furtherInformation": "string",
            "enterDate": "string",
            "lastReviewed": "string",
            "descriptions": [
              {
                "description1": "string",
                "description2": "string",
                "description3": "string",
              }
            ]
            "nameDetails": [
              {
                "nameType": "string",
                "firstName": "string",
                "middleName": "string",
                "lastName": "string",
              }
            ]
            "originalScriptNames": [
              "string"
            ]
            "roles": [
              {
                "title": "string",
                "from": "string",
                "to": "string",
                "type": "string",
                "status": "string",
                "country": "string",
              }
            ]
            "importantDates": [
              {
                "dateType": "string",
                "dateValue": "string",
              }
            ]
            "locations": [
              {
                "country": "string",
                "city": "string",
                "address": "string",
              }
            ]
            "countries": [
              {
                "countryType": "string",
                "countryValue": "string",
              }
            ]
            "officialLists": [
              {
                "keyword": "string",
                "category": "string",
                "description": "string",
                "country": "string",
                "isCurrent": true,
              }
            ]
            "idNumbers": [
              {
                "type": "string",
                "idNotes": "string",
                "number": "string",
              }
            ]
            "linkedIndividuals": [
              {
                "firstName": "string",
                "middleName": "string",
                "lastName": "string",
                "category": "string",
                "description": "string",
              }
            ]
            "linkedCompanies": [
              {
                "name": "string",
                "category": "string",
                "description": "string",
              }
            ]
            "sources": [
              {
                "url": "string",
                "categories": "string",
                "dates": "string",
              }
            ]
          }
    }
  ]
}

New Organisation Sapphire Scans

Code samples

# You can also use wget
curl -X post https://api.namescan.io/v3/organisation-scans/sapphire \
     -H "api-key: your-api-key" \
     -H "content-type: application/json" \
     -d "{'name':'al-shabab', 'exact':true }"

POST https://api.namescan.io/v3/organisation-scans/sapphire HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/organisation-scans/sapphire',
    method: 'post',
    headers: {'api-key': 'your-api-key'},
    data: {'name': 'al-shabab', 'excat': true},
    success: function(result) {
      console.log(JSON.stringify(result));
    }
  })
</script>

const request = require('node-fetch');
var data = {name: 'al-shabab', exact: true};
fetch('https://api.namescan.io/v3/organisation-scans/sapphire', {
    method: 'POST',
    headers: {'api-key': 'your-api-key', 'Content-Type': 'application/json'},
    body: JSON.stringify(data)
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.post 'https://api.namescan.io/v3/organisation-scans/sapphire', ...

    # TODO

p = JSON.parse(result)

import requests

header = {'api-key': 'your-api-key', 'Content-Type': 'application/json'}
data = {'name': 'al-shabab', 'exact': true}
r = requests.post('https://api.namescan.io/v3/organisation-scans/sapphire',
    headers = header, json = data)

print r.json()

URL obj = new URL("https://api.namescan.io/v3/organisation-scans/sapphire");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("api-key", "your api key");
con.setRequestProperty("Content-Type", "application/json");

con.setDoInput(true);
con.setDoOutput(true);

DataOutputStream output = new DataOutputStream(con.getOutputStream());
String data = "{\"name\":\"al-shabab\", \"exact\":true}";
output.writeBytes(data);
output.flush();
output.close();

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

POST /v3/organisation-scans/sapphire

Performs new organisation Sapphire scan

Allows you to scan organisations on Sapphire lists by entering their information into the fields provided.

Parameters

Parameter	In	Type	Required	Description
param	body	organisationScanSapphireParam	true	Organisation scan parameter, which includes organisation information to find. name is required. exact parameter is false by defualt and indicates that the exactly matched results or closely matched results should be returned. maxResultCount indicates the maximum number of matches that should be returned. It must be between 1 and 200; defaults to 100.

Body parameter

{
  "name": "string",
  "country": "string",
  "exact": true,
  "maxResultCount": 100
}

Responses

Status	Meaning	Description
201	Created	organisationScanSapphireResult: contains information of matched organisations.
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure

{
  "date": "2017-07-29T12:06:08Z",
  "scanId": "string",
  "numberOfMatches": 0,
  "corporates": [
    {
      "id": 0,
      "category": "string",
      "resultId": "string",
      "flag": 0,
      "entity": 
        {
          "uniqueId": "string",
          "categories": "string",
          "subcategory": "string",
          "primaryName": "string",
          "primaryLocation": "string",
          "furtherInformation": "string",
          "enterDate": "string",
          "lastReviewed": "string",
          "generalInfo": 
            {
              "nationality": "string",
              "alternateTitle": "string",
              "businessDescription": "string",
              "website": "string",
            }
          "descriptions": [
            {
              "description1": "string",
              "description2": "string",
              "description3": "string",
            }
          ]
          "nameDetails": [
            {
              "nameType": "string",
              "entityName": "string",
            }
          ]
          "originalScriptNames": [
            "string"
          ]
          "locations": [
            {
              "country": "string",
              "city": "string",
              "address": "string",
            }
          ]
          "countries": [
            {
              "countryType": "string",
              "countryValue": "string",
            }
          ]
          "officialLists": [
            {
              "keyword": "string",
              "category": "string",
              "description": "string",
              "country": "string",
              "isCurrent": true,
            }
          ]
          "idNumbers": [
            {
              "type": "string",
              "idNotes": "string",
              "number": "string",
            }
          ]
          "linkedIndividuals": [
            {
              "firstName": "string",
              "middleName": "string",
              "lastName": "string",
              "category": "string",
              "description": "string",
            }
          ]
          "linkedCompanies": [
            {
              "name": "string",
              "category": "string",
              "description": "string",
            }
          ]
          "sources": [
            {
              "url": "string",
              "categories": "string",
              "dates": "string",
            }
          ]
      }
    }
  ]
}

Scans History

The Scan History API's allow you to get scans history of all data source types.

Get Monthly Scan History

Code samples

# You can also use wget
curl -X get https://api.namescan.io/v3/scans/{year}/{month} \
     -H "api-key: your-api-key"

GET https://api.namescan.io/v3/scans/{year}/{month} HTTP/1.1
Host: localhost
Accept: application/zip
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/scans/{year}/{month}',
    method: 'get',
    xhrFields: {'responseType': 'blob'},
    headers: {'api-key': 'your-api-key'},
    success: function(response, status, request) {
	  var disposition = request.getResponseHeader('Content-Disposition');
	  var filename = disposition.split(';')[1].split('=')[1];
	  var blob = Blob([response], { type: 'application/zip' });
	  var link = document.createElement('a');
	  link.href = window.URL.createObjectURL(blob);
	  link.download = filename;
	  document.body.appendChild(link);
	  link.click();
	  document.body.removeChild(link);
    }
  })
</script>

const request = require('node-fetch');
fetch('https://api.namescan.io/v3/scans/{year}/{month}', {
    method: 'GET',
    headers: {'api-key': 'your-api-key'}
})
.then(function(res) {
    // save blob...
}).

require 'rest-client'

result = RestClient.get 'https://api.namescan.io/v3/scans/{year}/{month}', ...

    # TODO

import requests

header = {'api-key': 'your-api-key', 'Content-Type': 'application/json'}
response = requests.get('https://api.namescan.io/v3/scans/{year}/{month}',
			  headers = header, stream = true)

if response.status_code == 200 :
    if response.headers.get('Content-Disposition'):
        filename = response.headers.get('Content-disposition').split("=")[1]
        open(filename, 'wb').write(response.content)
        print('File successfully downlowded.')
else:
    print('Error downloading file.')

URL obj = new URL("https://api.namescan.io/v3/scans/{year}/{month}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("api-key", "your api key");

int responseCode = con.getResponseCode();

Map<String, List<String>> map = con.getHeaderFields();
String[] parts = map.get("Content-Disposition").toString().split("="); 
String fileName = parts[1].substring(0, parts[1].length() - 1);

Files.copy(con.getInputStream(), Paths.get(fileName), StandardCopyOption.REPLACE_EXISTING);

GET /v3/scans/{year}/{month}

Retrieve scans history

Allows you to retrieve monthly scan history of all source types in a zip file that includes json files.

Parameters

Parameter	In	Type	Required	Description
year	query	integer	true	Scan history year.
month	query	integer	true	Scan history month.

Responses

Status	Meaning	Description
200	OK	Contains content of a zip file that includes scan history in json files.
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure


  Content of a zip file that includes scan history of all sources in json files.
  The file name can be retrieved from Content-Disposition header.

Credits

The Credit APIs allow you to retrieve the remaining credits balance and expiry date for each data source.

Get Emerald Credits

Code samples

# You can also use wget
curl -X get https://api.namescan.io/v3/credits/emerald \
     -H "api-key: your-api-key"

GET https://api.namescan.io/v3/credits/emerald HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/credits/emerald',
    method: 'get',
    headers: {'api-key': 'your-api-key'},
    success: function(data) {
      console.log(JSON.stringify(data));
    }
  })
</script>

const request = require('node-fetch');
fetch('https://api.namescan.io/v3/credits/emerald', {
    method: 'GET',
    headers: {'api-key': 'your-api-key'}
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.namescan.io/v3/credits/emerald', ...

    # TODO

p = JSON.parse(result)

import requests

header = {'api-key': 'your-api-key'}
param = {'scan_id': 'your-scan-id'}
r = requests.get('https://api.namescan.io/v3/credits/emerald',
    headers = header, params = param)

print r.json()

URL obj = new URL("https://api.namescan.io/v3/credits/emerald");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("api-key", "your api key");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /v3/credits/emerald

Retrieve emerald credit information

Allows you to retrieve information about emerald credits. balance shows the number of remaining emerald credits. expiryDate indicates the date that credits will expire.

Responses

Status	Meaning	Description
200	OK	creditResult: contains balance and expiryDate of emerald credits.
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure

[
  {
    "balance": "integer",
    "expiryDate": "date"
  }
]

Get Sapphire Credits

Code samples

# You can also use wget
curl -X get https://api.namescan.io/v3/credits/sapphire \
     -H "api-key: your-api-key"

GET https://api.namescan.io/v3/credits/sapphire HTTP/1.1
Host: localhost
Content-Type: application/json
Accept: application/json
api-key: your-api-key

<script>
  $.ajax({
    url: 'https://api.namescan.io/v3/credits/sapphire',
    method: 'get',
    headers: {'api-key': 'your-api-key'},
    success: function(data) {
      console.log(JSON.stringify(data));
    }
  })
</script>

const request = require('node-fetch');
fetch('https://api.namescan.io/v3/credits/sapphire', {
    method: 'GET',
    headers: {'api-key': 'your-api-key'}
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.get 'https://api.namescan.io/v3/credits/sapphire', ...

    # TODO

p = JSON.parse(result)

import requests

header = {'api-key': 'your-api-key'}
param = {'scan_id': 'your-scan-id'}
r = requests.get('https://api.namescan.io/v3/credits/sapphire',
    headers = header, params = param)

print r.json()

URL obj = new URL("https://api.namescan.io/v3/credits/sapphire");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("api-key", "your api key");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

GET /v3/credits/sapphire

Retrieve sapphire credit information

Allows you to retrieve information about sapphire credits. balance shows the number of remaining sapphire credits. expiryDate indicates the date that credits will expire.

Responses

Status	Meaning	Description
200	OK	creditResult: contains balance and expiryDate of sapphire credits
400	Bad Request	Bad request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
500	Internal Server Error	Internal Server Error

Response structure

[
  {
    "balance": "integer",
    "expiryDate": "date"
  }
]