NameScan API Reference v1

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, and Python. 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.

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.

Scans

The scans API’s allow you to scan person and organisation.

New Person Sanction Scan

Code samples

# You can also use wget
curl -X post https://api.namescan.io/v1/person-scans/sanction \
     -H "api-key: your-api-key" \
     -H "content-type: application/json" \
     -d "{'first_name':'john', 'last_name':'smith'}"

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

<script>
  $.ajax({
    url: 'https://api.namescan.io/v1/person-scans/sanction',
    method: 'post',
    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/v1/person-scans/sanction', { method: 'POST'})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.post 'https://api.namescan.io/v1/person-scans/sanction', params:
  {
    # TODO
  }

p JSON.parse(result)

import requests

r = requests.post('https://api.namescan.io/v1/person-scans/sanction', params={
  # TODO
})

print r.json()

URL obj = new URL("https://api.namescan.io/v2/person-scans/emerald");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
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());

POST /v1/person-scans/sanction

Performs a new person sanction scan

Person Scan Sanction - Scan New allows you to scan persons on sanction lists by entering their information into the fields provided.

Parameters

Parameter	In	Type	Required	Description
param	body	person_scan_param	true	Person scan parameter, which includes person information to find. name or first_name/last_name is required.

Body parameter

{
  "name": "string",
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<name>string</name>
<first_name>string</first_name>
<middle_name>string</middle_name>
<last_name>string</last_name>

Responses

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

New Organisation Sanction Scan

Code samples

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

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

<script>
  $.ajax({
    url: 'https://api.namescan.io/v1/organisation-scans/sanction',
    method: 'post',
    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/v1/organisation-scans/sanction', { method: 'POST'})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.post 'https://api.namescan.io/v1/organisation-scans/sanction', params:
  {
    # TODO
  }

p JSON.parse(result)

import requests

r = requests.post('https://api.namescan.io/v1/organisation-scans/sanction', params={
  # TODO
})

print r.json()

URL obj = new URL("https://api.namescan.io/v1/organisation-scans/sanction");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
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());

POST /v1/organisation-scans/sanction

Performs a new organisation sanction scan

Organisation Scan Sanction - Scan New allows you to scan organisations on sanction lists by entering their information into the fields provided.

Parameters

Parameter	In	Type	Required	Description
param	body	organisation_scan_param	true	organisation_scan_param, which includes organisation information to find. name is required.

Body parameter

{
  "name": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<name>string</name>

Responses

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

New Person PEP Scan

Code samples

# You can also use wget
curl -X post https://api.namescan.io/v1/person-scans/pep \
     -H "api-key: your-api-key" \
     -H "content-type: application/json" \
     -d "{'name':'ashraf ghani'}"

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

<script>
  $.ajax({
    url: 'https://api.namescan.io/v1/person-scans/pep',
    method: 'post',
    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/v1/person-scans/pep', { method: 'POST'})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

result = RestClient.post 'https://api.namescan.io/v1/person-scans/pep', params:
  {
    # TODO
  }

p JSON.parse(result)

import requests

r = requests.post('https://api.namescan.io/v1/person-scans/pep', params={
  # TODO
})

print r.json()

URL obj = new URL("https://api.namescan.io/v1/person-scans/pep");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
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());

POST /v1/person-scans/pep

Performs a new person pep scan

Person Scan Sanction - Scan New allows you to scan persons on pep lists by entering their information into the fields provided.

Parameters

Parameter	In	Type	Required	Description
param	body	person_scan_param	true	Person scan parameter, which includes person information to find. name or first_name/last_name is required.

Body parameter

{
  "name": "string",
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string"
}

<?xml version="1.0" encoding="UTF-8" ?>
<name>string</name>
<first_name>string</first_name>
<middle_name>string</middle_name>
<last_name>string</last_name>

Responses

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