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:

CodeTechnical KeyDescription
20000000OKSuccessful request.
20100000CREATEDA resource has been created.
40000000BAD_REQUESTBad Request, invalid input provided.
40100000UNAUTHORIZEDAuthentication is required and has failed.
40400000NOT_FOUNDThe requested resource was not found.
42900000TOO_MANY_REQUESTSToo many requests, try again later.
50000000INTERNAL_SERVER_ERRORRequest failed due to to an internal server error.
50300000SERVICE_UNAVAILABLEService is currently unavailable.

Status 200XXXXX

Expand to see the Status 200 extended list.
IDTechnical KeyMessage
200000000DEFAULT_OKSuccessful request.
200000001JOB_SCHEDULEDThe job has been successfully scheduled for execution.
200000002JOB_WAITINGThis job is waiting for dependent job to finish before it can run.
200000003JOB_RUNNINGThe job is currently being executed.
200000004JOB_FINISHEDThe job came to an end and finished successfully.
200000005JOB_CANCELEDJob has been canceled.
200000006BULK_RUNNINGThe bulk is currently being executed.
200000007BULK_FINISHEDThe bulk has been executed successfully.
200000008BULK_CANCELEDBulk has been canceled.

Status 201XXXXX

Expand to see the Status 201 extended list.
IDStatus Technical KeyMessage
201000000DEFAULT_CREATEDA resource has been created.
201000001JOB_CREATEDA job has been initially created but is not accepted yet.
201000002JOB_PERSISTEDA job has been created and accepted.
201000003BULK_CREATEDA bulk has been created.

Status 400XXXXX

Expand to see the Status 400 extended list.
IDTechnical KeyMessage
400000000DEFAULT_BAD_REQUESTBad Request, invalid input provided.
400000001MALFORMED_REQUESTThe request is malformed. please check the documentation to construct a valid request.
400000002METHOD_NOT_SUPPORTEDRequest method '{1}' is not supported.
400000003NOT_FOUNDThe requested resource could not be found.
400000004MANDATORY_FIELDPlease provide {1}.
400100001NAME_OR_IDENTIFIER_MISSINGYou have to provide at lease name or identifier.
400100003GR_NON_UNIQUE_RESULTWe found multiple GRs in this business partner, please ensure to submit only 1.
400100002GR_NOT_FOUNDGolden Record not found.
400100004FETCH_STRATEGY_MISSINGYou have to use a fetch strategy if you provide a business partner.
400100005BP_AND_CDQID_PROVIDEDYou have provided a business partner and CDQ ID. Please provide only one.
400100006GR_BUSINESSPARTNER_MISSINGYou have to provide a business partner for this fetch strategy.

Status 404XXXXX

Expand to see the Status 404 extended list.
IDTechnical KeyMessage
404000000DEFAULT_NOT_FOUNDThe path you requested has not been found
404000001BULK_NOT_FOUNDBulk Id '{1}' does not exists. Either it never existed or it is evicted.

Status 429XXXXX

Expand to see the Status 429 extended list.
IDTechnical KeyMessage
429000000DEFAULT_TOO_MANY_REQUESTSToo many requests.
429000001RATE_LIMIT_EXCEEDEDToo many requests. Your rate limit is {1}.
429000002QUOTA_EXCEEDEDQuota exceeded for data source '{1}'. Your quota is reset in {1}.

Status 500XXXXX

Expand to see the Status 500 extended list.
IDTechnical KeyMessage
500000000DEFAULT_INTERNAL_SERVER_ERRORService failed due to to an internal server error. Please contact CDQ Support.
500000001JOB_FAILEDJob failed due to to an internal server error. Please contact CDQ Support.
500000002BULK_FAILEDBulk failed due to to an internal server error. Please contact CDQ Support. .

Status 503XXXXX

Expand to see the Status 503 extended list.
IDTechnical KeyMessage
503000000DEFAULT_SERVICE_UNAVAILABLEService is currently unavailable.
503100001EXTERNAL_SERVICE_ERRORRequest failed due to external service error.

Storing data

Storing space typeDescription
WorkspaceAn abstract area where customers can work. It contains the client's Data Mirror, Data Storages, Data Sources, configurations, and API Keys.
Data StorageStorage 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 MirrorA 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 SourceA 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.

FeatureDescription
LAB_*Feature toggle that is used temporarily to activate/deactivate beta features. Do no use in production environments.
ENABLE_SETTINGSEnables 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 ParameterDescription
limitSets the page size of the request object
startAfterStart 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

Copy
Copied
var startAfter = null
do
    var page = resource.readPage(limit, startAfter)
    process(page)
    startAfter = page.nextStartAfter
while (null != startAfter)

Integration Patterns

CDQ recommends different patterns to integrate with our SOAP or REST APIs:

  • Transactional: Process requests one-by-one.
  • Bulk: Parallelize processing by sending many requests into one. Bulk endpoints parallelize workload and optimize performance. Please note that for bulk endpoints different rate limits occur.
  • Data Mirror: Use continuously running monitors to process your data and distribute work loads.
  • Analytical: Dump analytical data and process on your own.

Use the following table to pick the proper integration pattern for your use case - depending on data volume and or expected throughput.

Integration PatternData VolumeMaximum Throughput
Transactional1< 20 per Second
Bulk2-1000> 20 per Second
Data Mirror> 1000Realtime
Analytical> 10005 MB per Second

Rate Limits

Rate limits helps to prevent short-term abuse and denial-of-service attacks and ensures that the API remains available for all customers. CDQ limits the number of REST API requests that you can make within a specific amount of time.

Rate Limits are tracked on a workspace, user or individual API Key level.

Following rate limits apply to all endpoints:

Rate LimitResetScope
5'000 RequestsHourWorkspace
2'000 RequestsHourUser
20 RequestsSecondAPI Key / User

For selected endpoints, we have additional limits:

  • Bulks: CDQ only allows one bulk of a type (i.e. Lookup or Fetch) processed sequentially. Keep in mind, that parallelization is applied on server side and parallelization on client-side is not required.
Rate LimitResetScope
1 Bulk per TypeAfter CompletionWorkspace

Quotas

Quotas control API utilization according to the selected subscription of every customer. Quotas helps to plan resources accordingly to ensure CDQ is able to meet service levels.

Please reach out to us in case you need to adjust quotas.

The following default quotas are set as part of your subscription:

Rate LimitResetScope
50 JobsDayWorkspace
100'000 RequestsMonthOrganization

CDQ also defines quotas for the access to external data sources.:

Rate LimitData SourceResetScope
40'0000 RequestsVIESDayOrganization

Firewall ports

For secure communication, the following ports are required for the CDQ Cloud Platform:

DescriptionProtocolPort
Inbound Agent CommunicationHTTP80
Inbound Agent CommunicationHTTPS443

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:

EndpointRequest Size
Upsert Business Partner250 MB

Upload file size

The same Request Size Limit applies to uploading the file.


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 Aug 07, 2024.

DomainCertificateProtocolsValid FromExpires
api.cdq.comDownloadTLS 1.227.07.202307.08.2024
api.corporate-data-league.chDownloadTLS 1.227.07.202307.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 RatingGrade A
Serial Number6cc6b06f29f5492eae45ea2e74dc7f27
KeyEC 256 bits
IssuerSSL.com SSL Intermediate CA ECC R2
Signature algorithmSHA384withECDSA
api.corporate-data-league.ch
Overall RatingGrade A
Serial Number51f12d971ca932581f6e34793bc513db
KeyEC 256 bits
IssuerSSL.com SSL Intermediate CA ECC R2
Signature algorithmSHA384withECDSA

RSA Certificates

For customers who do not support elliptic curve algorithm in their systems, we provide RSA certificates below.

DomainCertificateProtocolsValid FromExpires
api.cdq.comDownloadTLS 1.214.08.202313.08.2024
api.corporate-data-league.chDownloadTLS 1.226.07.202327.07.2024

History

DomainServer CertificateValid FromExpires
api.cdq.comDownload27.07.202207.08.2023
*.corporate-data-league.chDownload27.07.202207.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:

Copy
Copied
<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 is v1. Example:
Copy
Copied
https://api.cdq.com/reference-data/rest/businesspartners/lookup
https://api.cdq.com/reference-data/rest/businesspartners/v2/lookup
Features and fixes are provided to all previous releases If not stated explicitly otherwise, we provide features and fixes not only for the latest but also for all supported previous releases. Even though you may use a 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
tags

Version selector by tags

End-of-life

End of life of APIs or endpoints is communicated 1 year in advance to give every customer the necessary time to upgrade.

Beta Versions

Beta versions are introduced to provide developers with early access to the functionality and features of the API before its full release. This allows developers to test the API in real-world scenarios, provide feedback, and suggest improvements. Beta versions help to identify and address any issues or bugs or refine documentation. Additionally, beta testing enables developers to start integrating the API into their applications and services, allowing for smoother adoption and transition once the API is officially launched.

warning

Beta functionalities are not recommended to be implemented in a production environment.

API Beta Versions

APIs Beta versions are marked in the dropdown list with the (beta) flag next to the API version.
betaver
Version selector with beta flag

Endpoint Beta Versions

Endpoints Beta versions are marked with BETA badge in the API documentation next to the endpoint name.
attention
In close future the BETA version marking will be implemented for properties.

Parameters, properties and toggle features Beta Versions

Parameters, properties and toggle features Beta versions are marked with BETA badge in the API documentation next to the parameter, property or feature description.
warning
Beta badge in parameters, properties and toggle features are custom-made using html and css. If you download the API documentation beta version, delete the html tags from the tagged descriptions.

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 a lastPaymentDate as this information is null and hence omitted.
Response #1 - Field has a valueResponse #2 - Field has null value
Copy
Copied
{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  "lastPaymentDate" : "2021-18-45"
  "country" : "DE"
  ..
}
Copy
Copied
{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  // ATTENTION: field "lastPaymentDate" is null so it will not be part of the response
  "country" : "DE"
  ..
}
If you client implementation requires always the field 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
WSDL interfaces are only provided for endpoints which have the badge WSDL.
API NameJSONYAMLWSDLWADL
Bankaccount Data @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Bankaccount Data @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Data Clinic @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Data Clinic @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Data Compliance @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Data Compliance @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Data Curation @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Data Curation @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Data Exchange @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Data Exchange @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Data Exchange @ V3Download jsonDownload yamlDownload wsdlDownload wadl
Data Exchange @ V4Download jsonDownload yamlDownload wsdlDownload wadl
Data Exchange @ V5Download jsonDownload yamlDownload wsdlDownload wadl
Data Matching @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Data Matching @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Data Validation @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Data Validation @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Identity Management @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Knowledge Graph @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Metadata @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Metadata @ V3Download jsonDownload yamlDownload wsdlDownload wadl
Metadata @ V4Download jsonDownload yamlDownload wsdlDownload wadl
Protuct Identification @ V1Download jsonDownload yamlDownload wsdlDownload wadl
Reference Data @ V2Download jsonDownload yamlDownload wsdlDownload wadl
Reference Data @ V3Download jsonDownload yamlDownload wsdlDownload wadl
Reference Data @ V4Download jsonDownload yamlDownload wsdlDownload wadl
Salesforce @ V1Download jsonDownload yamlDownload wsdlDownload wadl
SAP DQM @ V1Download jsonDownload yamlDownload wsdlDownload wadl
SAP ODM @ V1Download jsonDownload yamlDownload wsdlDownload wadl
SAP ODM @ V2Download jsonDownload yamlDownload wsdlDownload wadl
SAP ODM @ V3Download jsonDownload yamlDownload wsdlDownload wadl
SAP BN @ V1Download jsonDownload yamlDownload wsdlDownload wadl

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