ADSuisse API (2.0.0)

Download OpenAPI specification:Download

Introduction

Integrating our application programming interface (API) is the easiest way to submit data to ADSuisse. In the following documentation, we will illustrate how you can get a full advantage of it by understanding and implementing all endpoints. With ADSuisse API you will be able to submit jobs containing personal or organizational data and receive refined and enriched entities. Requests are sent in a JSON format over HTTPS protocol, using a POST method.

On the right side of this OpenAPI format documentation, you can find example requests and responses that demonstrate how the communication is established. If you copy and paste the example code and use your individual API key (you can get one when you register on our site) you can test the endpoint.

We have to note that while testing you will receive an immediate response to your requests. However, in a real environment, our data processing will take more time. That is why we send a notification to a provided webhook address when the job is done. After that, you will be able to get the ready data.

Please, feel free to send us any questions on support@adsuisse.com

Authentication

Authentication of requests is acomplished by using an individual API key. You can generate one on the ADSuisse customer portal (via the API Key interface). During a tryout you will be provided with a test key that will not affect the real data.

For each API request you need to include the API key with a "Bearer" prefix. See the example on the right

Response codes and errors

Response codes indicate success or failure of data processing. Status codes from the 2XX range indicate that request has been accepted. If the returned code is from the 4XX range then it reveals either problem with the request or unability to discover new data.

Error Code Description
200 The request was successful
400 Invalid values / Bad Request
401 Unauthorized. It is usally caused by using a wrong API key or do not using one at all.
411 Too many requests (plase see Rate limits below)
405 Bad request
200 The request was successful
500 Internal Server Error. Please contact us at support@adsuisse.com

Rate limits

To provide equal access to our API customer requests are limited on a 60 seconds basis. Limits depend on your current subscription plan.

Subscription plan Rate limit per 60 seconds
Tryout (demo data) 60
Basic 300
Discovery Starter 600
Discovery Pro Unlimited

Webhooks

After we process and complete your request you we will be notified via webhook. You can provide ADSuisse with a specific webhook URL on the Customer Portal (see Webhooks section). You can test HTTP requests using a service like hookbin.com.

Test connectivity

The Ping Response Object

ping
object

returns the requested body as submitted

Response Sample

Copy
Expand all Collapse all
{
  • "ping": { }
}

Ping

By using the PING command you can send a POST request with an example JSON data to test connectivity & authentication. If ping is successful you will receive a pong containing some JSON response.

header Parameters
Content-Type
required
string

application/json

Authorization
required
string

Bearer {{api_token}}

Request Body schema: application/json
test
string

free form json or text

Responses

200

Successful operation

401

Unauthorized access

500

Internal server error

post /api/ping
ADSuisse production server
https://api.adsuisse.com/api/ping

Request samples

application/json
Copy
Expand all Collapse all
{
  • "test": "Hello World"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "ping":
    {
    }
}

Submit Jobs

The job object

The internal JobModel as it's stored and processed by the system

_id
string

readOnly the JOB id generated by ADSuisse

source
string

readOnly initial source name of the entity (i.e. ABC Bank)

sourceType
string

readOnly initial source type of the entity (i.e. API)

uid
string

The unique identifier of the entity within the external system. It serves the purpose of identifying ADSuisse's entities 1:1 within any external system - the source of that entity.

Any combination of source and uid (entityUid) MUST be unique

type
string
Enum:"person" "organisation" "unknown"

The type of the entity.

personData
object

If entity is a person / individual. An entity can be either a person or an organisation. The set of personal data used by ADSuisse is guided by the international standards for Machine-readable passports.

organisationData
object

If entity is an organisation (e.g. company). An entity can be either a person or an organisation.

addresses
Array of object

array of objects that stores addresses infromation.

contacts
Array of object

array of objects that stores contact information about the given entity

relatedEntities
Array of object

array of objects that contains related entities information

authorityIDs
Array of object

array of objects that contains authorityIds information.

events
Array of object

array of objects that stores events information.

additionalData
Array of object

customer data required for processing

updatedAt
date-time

Datetime of last change of the record at ADSuisse.

createdAt
date-time

Creation Datetime of the record at ADSuisse.

Response Sample

Copy
Expand all Collapse all
{
  • "_id": "5ae720ffd3b8ba5cb7cd7edb",
  • "source": "DeutcheBank",
  • "sourceType": "api",
  • "uid": "30f4s011",
  • "type": "person",
  • "personData":
    {
    },
  • "organisationData":
    {
    },
  • "addresses":
    [
    ],
  • "contacts":
    [
    ],
  • "relatedEntities":
    [
    ],
  • "authorityIDs":
    [
    ],
  • "events":
    [
    ],
  • "additionalData":
    [
    ],
  • "updatedAt": "2017-09-15T15:47:49.058Z",
  • "createdAt": "2017-09-15T15:47:49.058Z"
}

Submit a new JOB

With this POST request you are able to submit new entity(or entities) as a JOB to ADSuisse. You will receive a response with unique jobId. As soon as your JOB is processed you will be notified on the Webhook URL provided by you in the customer protal. Then you can use your jobId to review the job status or to receive the final result.

header Parameters
Content-Type
required
string

application/json

Authorization
required
string

Bearer {{api_token}}

Request Body schema: application/json
uid
string

The unique identifier of the entity within the external system. It serves the purpose of identifying ADSuisse's entities 1:1 within any external system - the source of that entity.

Any combination of source and uid (entityUid) MUST be unique

type
string
Enum:"person" "organisation" "unknown"

The type of the entity.

personData
object

If entity is a person / individual. An entity can be either a person or an organisation. The set of personal data used by ADSuisse is guided by the international standards for Machine-readable passports.

organisationData
object

If entity is an organisation (e.g. company). An entity can be either a person or an organisation.

addresses
Array of object

array of objects that stores addresses infromation.

contacts
Array of object

array of objects that stores contact information about the given entity

relatedEntities
Array of object

array of objects that contains related entities information

authorityIDs
Array of object

array of objects that contains authorityIds information.

events
Array of object

array of objects that stores events information.

additionalData
Array of object

customer data required for processing

Responses

200

Successful operation

401

Unauthorized access

405

Bad request

500

Internal server error

post /api/job
ADSuisse production server
https://api.adsuisse.com/api/job

Request samples

application/json
Copy
Expand all Collapse all
{
  • "uid": "30f4s011",
  • "type": "person",
  • "personData":
    {
    },
  • "organisationData":
    {
    },
  • "addresses":
    [
    ],
  • "contacts":
    [
    ],
  • "relatedEntities":
    [
    ],
  • "authorityIDs":
    [
    ],
  • "events":
    [
    ],
  • "additionalData":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "jobId": "5ae720ffd3b8ba5cb7cd7edb"
}

Receive Entities

The Entity object

The entity object requires exactly one property of person or organisation

_id
string

readOnly the ENTITY id, generated by ADSuisse

uids
Array of object

array of uids that stores all unique identifier within the customer's system of all given entities

people
Array of object

array of personData that stores personal information about the given entity

organisations
Array of object

array of organisationData that stores organisational information about the given entity

addresses
Array of object

The address information of the customer contains different attributes, e.g. address lines for street names and numbers, zip codes and cities. You can submit an unlimited number of addresses.

contacts
Array of object

The contact object allows you to submit various contact records of the costumer, e.g. phone numbers, eMail adresses, website URLs, messenger IDs, social media profiles. You can submit an unlimited number of contact records.

relatedEntities
Array of object

array of relatedEntities and relationTypes related to given entity

authorityIDs
Array of object

Array of objects that stores authorityIds information

events
Array of object

array of objects that stores events information.

additionalData
Array of object

customer data required for processing

pool
object

readOnly information about the entity within the current pool

poolHistory
Array of object

readOnly illustrates how the entity moved trough pools

job
object

ADSuisse's internal information about the related job.

meta
object

The MetaObject tracks contextual information of any record. Those are the origin of data and validity informations.

updatedAt
date-time

Datetime of last change of the record at ADSuisse.

createdAt
date-time

Creation Datetime of the record at ADSuisse.

Response Sample

Copy
Expand all Collapse all
{
  • "_id": "5ae720ffd3b8ba5cb7cd7edb",
  • "uids":
    [
    ],
  • "people":
    [
    ],
  • "organisations":
    [
    ],
  • "addresses":
    [
    ],
  • "contacts":
    [
    ],
  • "relatedEntities":
    [
    ],
  • "authorityIDs":
    [
    ],
  • "events":
    [
    ],
  • "additionalData":
    [
    ],
  • "pool":
    {
    },
  • "poolHistory":
    [
    ],
  • "job":
    {
    },
  • "meta":
    {
    },
  • "updatedAt": "2017-09-15T15:47:49.058Z",
  • "createdAt": "2017-09-15T15:47:49.058Z"
}

Get Entity by ID

You can request entity details by given entityId. As a result you will receive single entitiy and related jobIds. Endpoint /api/entities is aliased to /api/entity

header Parameters
Content-Type
required
string

application/json

Authorization
required
string

Bearer {{api_token}}

Responses

200

successful operation

400

Invalid value

401

Unauthorized access

404

Not found

500

Internal server error

get /api/entities/{entityId}
ADSuisse production server
https://api.adsuisse.com/api/entities/{entityId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "entityId": "5ae720ffd3b8ba5cb7cd7edb",
  • "jobIds":
    [
    ],
  • "uids":
    [
    ],
  • "type": "person",
  • "personData":
    {
    },
  • "organisationData":
    {
    },
  • "addresses":
    [
    ],
  • "contacts":
    [
    ],
  • "relatedEntities":
    [
    ],
  • "authorityIDs":
    [
    ],
  • "events":
    [
    ],
  • "additionalData":
    [
    ]
}