Developer Guidelines
Status and Error Codes
Following list describes common types of client statuses on API calls that receive request bodies: All CDQ Cloud Platform services provide a response object comprising an HTTP status code and optionally a response entity (e.g. a business partner). The response entities are described by the particular web method documentation. The following listing defines the meaning of HTTP status codes in the context of CDQ Cloud Platform services:
Code | Technical Key | Description |
---|---|---|
20000000 | OK | Successful request. |
20100000 | CREATED | A resource has been created. |
40000000 | BAD_REQUEST | Bad Request, invalid input provided. |
40100000 | UNAUTHORIZED | Authentication is required and has failed. |
40400000 | NOT_FOUND | The requested resource was not found. |
42900000 | TOO_MANY_REQUESTS | Too many requests, try again later. |
50000000 | INTERNAL_SERVER_ERROR | Request failed due to to an internal server error. |
50300000 | SERVICE_UNAVAILABLE | Service is currently unavailable. |
Status 200XXXXX
Expand to see the Status 200 extended list.
Code | Technical Key | Description |
---|---|---|
20000000 | OK | Successful request. |
20000001 | GR_FOUND | Golden record found successfully. |
20000002 | JOB_SCHEDULED | The job has been successfully scheduled for execution. |
20000003 | JOB_WAITING | This job is waiting for dependent job to finish before it can run. |
20000004 | JOB_RUNNING | The job is currently being executed. |
20000005 | JOB_FINISHED | The job came to an end and finished successfully. |
20000006 | BULK_RUNNING | The bulk is currently being executed. |
20000007 | BULK_FINISHED | The bulk has been executed successfully. |
Status 201XXXXX
Expand to see the Status 201 extended list.
Code | Technical Key | Description |
---|---|---|
20100000 | CREATED | A resource has been created. |
20100001 | JOB_CREATED | A job has been initially created but is not accepted yet. |
20100002 | JOB_PERSISTED | A job has been created and accepted. |
20100003 | BULK_CREATED | A bulk has been created. |
Status 400XXXXX
Expand to see the Status 400 extended list.
Code | Technical Key | Description |
---|---|---|
40000000 | BAD_REQUEST | Bad Request, invalid input provided. |
40000001 | GR_NOT_HIGHEST_SCORE | Golden Record found, but it does not have the highest matching score. |
40000002 | GR_NOT_FOUND | Golden Record not found. |
40000003 | GR_NON_UNIQUE_RESULT | We found multiple GRs in this business partner, please ensure to submit only 1. |
40000004 | GR_BUSINESSPARTNER_MISSING | You have to provide a business partner for this fetch strategy. client error. |
40000005 | FETCH_STRATEGY_MISSING | You have to select a fetch strategy if you provide a business partner. |
40000006 | MALFORMED_REQUEST | The request is malformed. please check the documentation to construct a valid request. |
40000007 | NOT_FOUND | The requested resource could not be found. |
40000008 | JOB_CANCELED | Job has been canceled. |
40000009 | BULK_CANCELED | Bulk has been canceled. |
Status 429XXXXX
Expand to see the Status 429 extended list.
Code | Technical Key | Description |
---|---|---|
42900000 | TOO_MANY_REQUESTS | Too many requests, try again later. |
Status 500XXXXX
Expand to see the Status 500 extended list.
Code | Technical Key | Description |
---|---|---|
50000000 | INTERNAL_SERVER_ERROR | Request failed due to to an internal server error. |
50000001 | SERVICE_FAILED | Service failed. |
50000002 | JOB_FAILED | Job failed. |
50000003 | BULK_FAILED | Bulk failed. |
Storing data
Storing space type | Description |
---|---|
Workspace | An abstract area where customers can work. It contains the client's Data Mirror, Data Storages, Data Sources, configurations, and API Keys. |
Data Storage | Storage dedicated for client's data. Multiple Data Storages can be created in the organization's workspace. Data stored in the Data Storage can not be shared with the CDQ community. |
Data Mirror | A special type of storage dedicated to client's data. Only one Data Mirror is created in the organization's workspace. Data Mirror can be shared with the CDQ community. |
Data Source | A partition-like space. Multiple Data Sources can be created in the Data Storage or Data Mirror. |
Features and Profiles
Endpoints provide features in order to enable configurability to optimize performance. Features are very specific to the endpoint, however, following generic features can be distinguished.
Feature | Description |
---|---|
LAB_* | Feature toggle that is used temporarily to activate/deactivate beta features. Do no use in production environments. |
ENABLE_SETTINGS | Enables that organizational and/or user settings are applied to configure the endpoint. For example, organization-wide configuration for data curation output languages. |
SHOW _* | Feature which add additional fields to the response object. By default, these fields are hidden in order to keep the payload low and to increase performance |
For convenience, most common configurations of the features are provided in terms of profiles which also can be selected in the endpoint. If no profile or feature is selected explicitly, a default profile will always be applied. In most cases, consumers do not need to configure features or profiles - they may use the endpoints as-is.»
Pagination
Responses that return multiple items will be paginated to 50 items by default. You can specify further pages control with the following query parameter:
Query Parameter | Description |
---|---|
limit | Sets the page size of the request object |
startAfter | Start after the provided pagination ID. Leave empty for the first query. The response will contain a property nextStartAfter which need to be used for any subsequent queries until nextStartAfter is empty. |
Paging over whole resource
The whole resource can be retrieved using endpoint supporting pagination. Reading loop should include page read endpoint call with startAfter property, filled with the content of nextStartAfter from the previous page read result. When nextStartAfter property is empty, then reading loop should finish processing.
Example
var startAfter = null
do
var page = resource.readPage(limit, startAfter)
process(page)
startAfter = page.nextStartAfter
while (null != startAfter)
Quotas
For every customer we apply the following quotas:
- Maximum of 50 jobs per day per workspace.
Firewall ports
For secure communication, the following ports are required for the CDQ Cloud Platform:
Description | Protocol | Port |
---|---|---|
Inbound Agent Communication | HTTP | 80 |
Inbound Agent Communication | HTTPS | 443 |
Rate Limiting
Rate limiting is per API Key. Default is 20 requests per second maximum.
Request Size Limiting
Payload size
For most CDQ's endpoints, the maximum acceptable payload size of the request is set to 10 MB.
Exceptions from this limit are gathered in below table:
Endpoint | Request Size |
---|---|
Upsert Business Partner | 250 MB |
Upload file size
The same Request Size Limit applies to uploading the file.
- For uploading files <= 10 MB read File Upload instruction.
- For uploading files > 10 MB read Request Upload instruction.
Schema
Blank fields are omitted and not includes as null in order to optimize payload sizes. All timestamps are returned to ISO 8601 format
attention
Implementation Guidelines Carefully read and follow our integration guideline S1: Safe consumption of responses.
TLS Certificates
When connecting to our API, it may be necessary for some particular clients to explicitly download and import the TLS certificate chain (Root, Intermediate, Server). Please download the certificate chain here:
Currently active
attention
The following certificates will be active to Jul 07, 2024.
Domain | Certificate | Protocols | Valid From | Expires |
---|---|---|---|---|
api.cdq.com | Download | TLS 1.2 | 27.07.2023 | 07.08.2024 |
api.corporate-data-league.ch | Download | TLS 1.2 | 27.07.2023 | 07.08.2024 |
Please note that the certificates are renewed every year and need to be updated in your certificate management system (if available).
Certificate Details
The certificates were rated A at the time of issue, according to SSL Labs.
The details of the certificates are as follows:
api.cdq.com | |
---|---|
Overall Rating | Grade A |
Serial Number | 6cc6b06f29f5492eae45ea2e74dc7f27 |
Key | EC 256 bits |
Issuer | SSL.com SSL Intermediate CA ECC R2 |
Signature algorithm | SHA384withECDSA |
api.corporate-data-league.ch | |
---|---|
Overall Rating | Grade A |
Serial Number | 51f12d971ca932581f6e34793bc513db |
Key | EC 256 bits |
Issuer | SSL.com SSL Intermediate CA ECC R2 |
Signature algorithm | SHA384withECDSA |
RSA Certificates
For customers who do not support elliptic curve algorithm in their systems, we provide RSA certificates below.
Domain | Certificate | Protocols | Valid From | Expires |
---|---|---|---|---|
api.cdq.com | Download | TLS 1.2 | 14.08.2023 | 13.08.2024 |
api.corporate-data-league.ch | Download | TLS 1.2 | 26.07.2023 | 27.07.2024 |
History
Domain | Server Certificate | Valid From | Expires |
---|---|---|---|
api.cdq.com | Download | 27.07.2022 | 07.08.2023 |
*.corporate-data-league.ch | Download | 27.07.2022 | 07.08.2023 |
Versioning
Understanding version numbers
Each API or App release is uniquely identified by a version number. The structure of the version follows the standards of Semantic Versioning 2.0.
Format and example:
<MAJOR>.<MINOR>.0+<BUILD TAG>
25 .45 .0+202007747438
- Major: Incremented when incompatible API changes are releases
- Minor: Incremented when functionality or fixes are released in a backwards compatible manner
- Build: Timestamp of the build
Each API or App has its own release cycle and thus its own dedicated version. Release notes are published here.
Incompatible API changes
Incompatible API changes include ("breaking changes"):
- End-of-life of an endpoint
- Removal of a property in the request/response model
- Removal of an enum value in the request/response model
Versioning and release strategy
In order to support and operate multiple API versions in parallel, we apply the following versioning strategy:
Versioning through URI paths Endpoints include the major version number in order to provide two version in parallel. If no version number is provided, the version isv1
. Example:https://api.cdq.com/reference-data/rest/businesspartners/lookup
https://api.cdq.com/reference-data/rest/businesspartners/v2/lookup
v1
endpoint, you
still benefit from (non-breaking) features or fixes.Tags
The following tags are used in the API documentation for quick reference to versions.
- V1, V2, .. ,VX: Refers to the major version of an API
- latest: Refers to the latest version of an API

Version selector by tags
End-of-life
End of life of APIs or endpoints is communicated1 year
in advance to give every customer the necessary time to
upgrade.Implementation
Schema
The following guidelines support developers to build rocket-solid client implementations.
S1: Safe consumption of API responses Be aware that in the API response blank fields are omitted and not included as null. Your client implementation needs to check if values are present in the payload before using them - otherwise your application may generate null pointer exceptions or similar.
Here is the example of two responses of the same API endpoint - however, in the second response we don't provide alastPaymentDate
as this information is null and hence omitted.{
"internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
"lastPaymentDate" : "2021-18-45"
"country" : "DE"
..
}
{
"internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
// ATTENTION: field "lastPaymentDate" is null so it will not be part of the response
"country" : "DE"
..
}
lastPaymentDate
in every response then Response #2 will
definitely lead to an application error which needs to be avoided.Specifications
CDQ APIs are available via REST or SOAP 1.2. The below table provides links to download CDQ APIs specification in JSON, YAML, WSDL or WADL format.
attention
Your opinion matters!
We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!
Mail our developer-portal team: developer-portal@cdq.com