Skip to content

Referencedata API (4)

This API provides services to search and read reference data

Overview
URL

https://www.cdq.ch/team

Krystian Sola

krystian.sola@cdq.ch

Languages
Servers
Mock server

https://idp.cdq.com/_mock/apis/referencedata-api/api-v4/

Production SOAP

https://api.corporate-data-league.ch/referencedata/soap/v4/

Production

https://api.corporate-data-league.ch/referencedata/

Business Partners

Everything about Business Partners

Operations

Analytics

Everything about reference data analytics

Registrations

Registrations

Operations

Addresses

Everything about Addresses

Operations

Bulk Fetch

Operations

Bulk Lookup

Operations

Cancel Bulk

Operations

CEDEX Lookup

Operations

Batch Lookup

Operations

Start Lookup Job

Request

Initialisation of a lookup job. The job will be executed asynchronously. The response contains the job ID which can be used to poll for the status of the job.

Security
basicAuth
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired

cmd

storageIdstring

The storage ID for which the batch lookup should be done.

Example: "72d6900fce6b326088f5d9d91049e3e6"
optionReportNamestring

The report name. If a report with that name exists in S3 it will be overwritten. If report name is empty the report name will be the storage ID.

Example: "MyReport"
optionSkipLookupboolean

Skip Lookup.

Default false
Example: "false"
optionBatchLookupJobIdstring

Provide the ID of batch lookup job which produced the matches. Providing this option make sens with optionSkipLookup set to true.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
optionShowAllboolean

Display also entries without matches.

Default false
Example: "true"
optionMatchingThresholdstring

The matching threshold. When not set then all entries are taken into consideration.

Example: "0.8"
optionReportMatchingThresholdstring

The matching threshold used to filter out results in report.

Example: "0.8"
optionCandidatesinteger

Define number of candidates taken into consideration in the matching process.

Default 20
Example: "15"
optionMatchingConfigurationstring

Provide the name of the matching configuration. When not set then the default configuration is used.

Default "DEFAULT"
Example: "DEFAULT"
optionDataMatchingDefinitionIdstring

Provide the id of the data matching definition id. When id wrongly set then no matching score will be provided.

Example: "6461e6113b1865304b3038b6"
optionDelayinteger

Add a delay between next lookup calls in milliseconds (example 3000 = 3s).

Example: "3000"
dataSourceIdsArray of strings(BusinessPartnerStorageDataSourceId)

If set, only the records that belong to the data sources identified by these IDs are processed. By default, all records of the storage (means from all data sources) are processed (considering other filters).

Example: ["648824a691d8d2503d65103e"]
countryShortNamesArray of strings(CountryShortName)

If set, only the records that belong to the countries identified by these short names are processed. By default, all records of the storage (means from all countries) are processed (considering other filters).

Example: ["CH"]
configurationIdstring

Configuration ID used to set up lookup. If provided, those parameters will be affected. If any of them is provided in this request, will overwrite one from configuration (except for features which are merged):

  • dataSource
  • dataMatchingDefinitionId
  • matchingThreshold
  • maxCandidates
  • pageSize
  • featuresOn
  • featuresOff
Example: "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4"
processingLogobject(ProcessingLog)

ID of the processing log.

storagesDataSourcesArray of objects

This field allows to filter data mirrors that will be queried. For each data mirror, data sources can also be filtered. Leave empty to include all available data mirrors in query.

featuresOnArray of strings

The features with which the lookup should be called.

Example: ["ACTIVATE_DATASOURCE_BVD"]
featuresOffArray of strings

The features switched off in the lookup.

Example: ["ACTIVATE_DATASOURCE_BVD"]
optionSkipExcelReportbooleanDeprecated

To generate report use POST /referencedatareports.

Default false
Example: "true"
curl -i -X POST \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/referencedata-api/api-v4/public/lookupjobs \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "storageId": "72d6900fce6b326088f5d9d91049e3e6",
    "optionReportName": "MyReport",
    "optionSkipLookup": "false",
    "optionBatchLookupJobId": "35f23c03-1c22-45fe-9484-3ffe769325de",
    "optionSkipExcelReport": "true",
    "optionShowAll": "true",
    "optionMatchingThreshold": "0.8",
    "optionReportMatchingThreshold": "0.8",
    "optionCandidates": "15",
    "optionMatchingConfiguration": "DEFAULT",
    "optionDataMatchingDefinitionId": "6461e6113b1865304b3038b6",
    "optionDelay": "3000",
    "dataSourceIds": [
      "648824a691d8d2503d65103e"
    ],
    "countryShortNames": [
      "CH"
    ],
    "configurationId": "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4",
    "processingLog": {
      "id": "OVERLAP_LOG",
      "trigger": {
        "type": "INITIALIZED",
        "provenance": {
          "technicalKey": "VIES",
          "cdqId": "VIES:PL8660001429"
        },
        "details": {
          "value": "123"
        }
      },
      "replyQueue": "647328648329632-34890742-3432"
    },
    "storagesDataSources": [
      {
        "storageId": "72d6900fce6b326088f5d9d91049e3e6",
        "dataSources": [
          "648824a691d8d2503d65103e"
        ]
      }
    ],
    "featuresOn": [
      "ACTIVATE_DATASOURCE_BVD"
    ],
    "featuresOff": [
      "ACTIVATE_DATASOURCE_BVD"
    ]
  }'

Responses

OK

Bodyapplication/json
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
statusstring(JobStatus)

Job execution status.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job could not be started.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

CANCELED

Job has been canceled due to invalid input configuration.

Example: "RUNNING"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(UserId)

Unique ID of a user.

Example: "johndoe"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
Response
application/json
{
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "status": "RUNNING",
  "createdAt": "2020-08-31T16:47+00:00",
  "user": "johndoe",
  "progress": "77"
}

Poll Lookup Job

Request

After you have started a curation job, you will receive a job id in the response: { 'id' : '' } Use this ID to poll for the status of the job using this endpoint. Once the status is FINISHED, you can download the results.

Security
basicAuth
Path
idstringrequired

ID of the lookup job.

Example: cbed7ac6-a97d-4c23-9060-2a88fa660957
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/referencedata-api/api-v4/public/lookupjobs/cbed7ac6-a97d-4c23-9060-2a88fa660957 \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
statusstring(JobStatus)

Job execution status.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job could not be started.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

CANCELED

Job has been canceled due to invalid input configuration.

Example: "RUNNING"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(UserId)

Unique ID of a user.

Example: "johndoe"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
Response
application/json
{
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "status": "RUNNING",
  "createdAt": "2020-08-31T16:47+00:00",
  "user": "johndoe",
  "progress": "77"
}

Read DNB Lookup Job results

Request

Reads the results of a DNB lookup job by job ID.

Security
basicAuth
Path
idstringrequired

ID of the lookup job.

Example: cbed7ac6-a97d-4c23-9060-2a88fa660957
Query
businessPartnerIdArray of strings(BusinessPartnerId)

Business Partner IDs which should be filtered.

Example: businessPartnerId=63e635235c06b7396330fe40
startAfterstring

Pagination cursor which should be filled with nextStartAfter value provided in the previous page read response.

Default "0"
Example: startAfter=16
limitinteger(int32)[ 1 .. 1000 ]

Number of items to be returned on the page.

Default 100
Example: limit=20
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/referencedata-api/api-v4/public/dnb/lookupjobs/cbed7ac6-a97d-4c23-9060-2a88fa660957/results \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
nextStartAfterstring(NextStartAfter)

Provides a value to be used as a startAfter in next page request.

Example: "5712566172571652"
limitinteger(Limit)

Number of items per page.

Example: "100"
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
valuesArray of objects(DnbLookupJobItemResult)

List of DNB Lookup Job results.

Response
application/json
{
  "startAfter": "5712566172571652",
  "nextStartAfter": "5712566172571652",
  "limit": "100",
  "total": "67",
  "values": [
    { … }
  ]
}

Start DNB Lookup Job

Request

Initialisation of a DNB lookup job. The job will be executed asynchronously. The response contains the job ID which can be used to poll for the status of the job.

Security
basicAuth
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired

cmd

storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
dnbUserstring

Optional if credentials are available in user or organization settings.

Example: "myDnbUser"
dnbPasswordstring

Optional if credentials are available in user or organization settings.

Example: "myDnbPassword"
modestring

MATCH contains just the match results while EXTENDED_MATCH also includes D&B products (attention increased costs)

Enum"EXTENDED_MATCH""MATCH"
Example: "EXTENDED_MATCH"
featuresOnArray of strings(DnbLookupJobFeature)

List of features to be activated in the lookup.

Items Enum ValueDescription
INCREMENT

Continue processing after the last processed result with a goal to run on newly created business partners from a storage.

ENABLE_PARTIAL_QUOTA_CONSUMPTION

Enables to run import job on a remaining quota when full quota not available.

ACTIVATE_MASTER_DATA_EXTENDED

Enables to use data blocks instead of cmplek when fetching data from DNB.

SKIP_DNB_IMPORT

If it is not used, all DUNS will be fetched from DNB. Should be used in combination with ENRICH_COMMERCIAL_ULTIMATE to only load what is needed for commercial ultimate calculation.

ENRICH_COMMERCIAL_ULTIMATE

Calculate commercial ultimate for each business partner in storage.

Example: ["INCREMENT"]
featuresOffArray of strings(DnbLookupJobFeature)

List of features to be deactivated in the lookup.

Items Enum ValueDescription
INCREMENT

Continue processing after the last processed result with a goal to run on newly created business partners from a storage.

ENABLE_PARTIAL_QUOTA_CONSUMPTION

Enables to run import job on a remaining quota when full quota not available.

ACTIVATE_MASTER_DATA_EXTENDED

Enables to use data blocks instead of cmplek when fetching data from DNB.

SKIP_DNB_IMPORT

If it is not used, all DUNS will be fetched from DNB. Should be used in combination with ENRICH_COMMERCIAL_ULTIMATE to only load what is needed for commercial ultimate calculation.

ENRICH_COMMERCIAL_ULTIMATE

Calculate commercial ultimate for each business partner in storage.

Example: ["INCREMENT"]
dnbDataSourcestring

D&B name of the product to be used in the job.

Default "DNB"
Enum ValueDescription
DNB

D&B Master Data

DNB_MASTER_DATA_BASIC

D&B Master Data Basic

DNB_MASTER_DATA_PLUS_MGMT

D&B Master Data Plus Management

DNB_MASTER_DATA_PLUS_LINKAGE

D&B Master Data Plus Linkage

DNB_MASTER_DATA_EXTENDED

D&B Master Data Extended

DNB_LINKAGE_LNKELI

D&B Linkage LNKELI

Example: "DNB_MASTER_DATA_EXTENDED"
dataSourcesArray of strings(DataSources)

IDs of Data Sources in specified Data Mirror to be included during lookup. Leave empty to include all Data Dources.

Example: ["648824a691d8d2503d65103e"]
curl -i -X POST \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/referencedata-api/api-v4/public/dnb/lookupjobs \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "storageId": "72d6900fce6b326088f5d9d91049e3e6",
    "dnbUser": "myDnbUser",
    "dnbPassword": "myDnbPassword",
    "mode": "EXTENDED_MATCH",
    "featuresOn": [
      "INCREMENT"
    ],
    "featuresOff": [
      "INCREMENT"
    ],
    "dnbDataSource": "DNB_MASTER_DATA_EXTENDED",
    "dataSources": [
      "648824a691d8d2503d65103e"
    ]
  }'

Responses

OK

Bodyapplication/json
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
statusstring(JobStatus)

Job execution status.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job could not be started.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

CANCELED

Job has been canceled due to invalid input configuration.

Example: "RUNNING"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
createdBystring(CreatedBy)

Creator of a resource.

Example: "76248934691294444"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
resultobject(DnbLookupJobResult)

Lookup Job result for D&B data.

modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
statusMessagestring(JobStatusMessage)

Additional information to explain the status.

Example: "The job failed because storage is empty."
Response
application/json
{
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "status": "RUNNING",
  "createdAt": "2020-08-31T16:47+00:00",
  "createdBy": "76248934691294444",
  "progress": "77",
  "result": {
    "statistics": { … }
  },
  "modifiedAt": "2020-08-31T16:47+00:00",
  "statusMessage": "The job failed because storage is empty."
}

Poll DNB Lookup Job

Request

After you have started a curation job, you will receive a job id in the response: { 'id' : '' } Use this ID to poll for the status of the job using this endpoint. Once the status is FINISHED, you can download the results.

Security
basicAuth
Path
idstringrequired

ID of the DNB lookup job.

Example: cbed7ac6-a97d-4c23-9060-2a88fa660957
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/referencedata-api/api-v4/public/dnb/lookupjobs/cbed7ac6-a97d-4c23-9060-2a88fa660957 \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
statusstring(JobStatus)

Job execution status.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job could not be started.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

CANCELED

Job has been canceled due to invalid input configuration.

Example: "RUNNING"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
createdBystring(CreatedBy)

Creator of a resource.

Example: "76248934691294444"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
resultobject(DnbLookupJobResult)

Lookup Job result for D&B data.

modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
statusMessagestring(JobStatusMessage)

Additional information to explain the status.

Example: "The job failed because storage is empty."
Response
application/json
{
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "status": "RUNNING",
  "createdAt": "2020-08-31T16:47+00:00",
  "createdBy": "76248934691294444",
  "progress": "77",
  "result": {
    "statistics": { … }
  },
  "modifiedAt": "2020-08-31T16:47+00:00",
  "statusMessage": "The job failed because storage is empty."
}

Batch Lookup Result

Operations

Administrative Area Index

Operations

DNB

Operations

Configurations

Operations

Processing Logs

Operations