# Developer Guidelines

## Status and Error Codes

The 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**

details
summary
Expand to see the Status 200 extended list.
| ID | Technical Key | Message |
|  --- | --- | --- |
| 200000000 | DEFAULT_OK | Successful request. |
| 200000001 | JOB_SCHEDULED | The job has been successfully scheduled for execution. |
| 200000002 | JOB_WAITING | This job is waiting for dependent job to finish before it can run. |
| 200000003 | JOB_RUNNING | The job is currently being executed. |
| 200000004 | JOB_FINISHED | The job came to an end and finished successfully. |
| 200000005 | JOB_CANCELED | Job has been canceled. |
| 200000006 | BULK_RUNNING | The bulk is currently being executed. |
| 200000007 | BULK_FINISHED | The bulk has been executed successfully. |
| 200000008 | BULK_CANCELED | Bulk has been canceled. |


**Status 201XXXXX**

details
summary
Expand to see the Status 201 extended list.
| ID | Status Technical Key | Message |
|  --- | --- | --- |
| 201000000 | DEFAULT_CREATED | A resource has been created. |
| 201000001 | JOB_CREATED | A job has been initially created but is not accepted yet. |
| 201000002 | JOB_PERSISTED | A job has been created and accepted. |
| 201000003 | BULK_CREATED | A bulk has been created. |


**Status 400XXXXX**

details
summary
Expand to see the Status 400 extended list.
| ID | Technical Key | Message |
|  --- | --- | --- |
| 400000000 | DEFAULT_BAD_REQUEST | Bad Request, invalid input provided. |
| 400000001 | MALFORMED_REQUEST | The request is malformed. please check the documentation to construct a valid request. |
| 400000002 | METHOD_NOT_SUPPORTED | Request method '{1}' is not supported. |
| 400000003 | NOT_FOUND | The requested resource could not be found. |
| 400000004 | MANDATORY_FIELD | Please provide {1}. |
| 400100001 | NAME_OR_IDENTIFIER_MISSING | You have to provide at lease name or identifier. |
| 400100003 | GR_NON_UNIQUE_RESULT | We found multiple GRs in this business partner, please ensure to submit only 1. |
| 400100002 | GR_NOT_FOUND | Golden Record not found. |
| 400100004 | FETCH_STRATEGY_MISSING | You have to use a fetch strategy if you provide a business partner. |
| 400100005 | BP_AND_CDQID_PROVIDED | You have provided a business partner and CDQ ID. Please provide only one. |
| 400100006 | GR_BUSINESSPARTNER_MISSING | You have to provide a business partner for this fetch strategy. |


**Status 404XXXXX**

details
summary
Expand to see the Status 404 extended list.
| ID | Technical Key | Message |
|  --- | --- | --- |
| 404000000 | DEFAULT_NOT_FOUND | The path you requested has not been found |
| 404000001 | BULK_NOT_FOUND | Bulk Id '{1}' does not exists. Either it never existed or it is evicted. |


**Status 429XXXXX**

details
summary
Expand to see the Status 429 extended list.
| ID | Technical Key | Message |
|  --- | --- | --- |
| 429000000 | DEFAULT_TOO_MANY_REQUESTS | Too many requests. |
| 429000001 | RATE_LIMIT_EXCEEDED | Too many requests. Your rate limit is {1}. |
| 429000002 | QUOTA_EXCEEDED | Quota exceeded for data source '{1}'. Your quota is reset in {1}. |


**Status 500XXXXX**

details
summary
Expand to see the Status 500 extended list.
| ID | Technical Key | Message |
|  --- | --- | --- |
| 500000000 | DEFAULT_INTERNAL_SERVER_ERROR | Service failed due to to an internal server error. Please contact CDQ Support. |
| 500000001 | JOB_FAILED | Job failed due to to an internal server error. Please contact CDQ Support. |
| 500000002 | BULK_FAILED | Bulk failed due to to an internal server error. Please contact CDQ Support. . |


**Status 503XXXXX**

details
summary
Expand to see the Status 503 extended list.
| ID | Technical Key | Message |
|  --- | --- | --- |
| 503000000 | DEFAULT_SERVICE_UNAVAILABLE | Service is currently unavailable. |
| 503100001 | EXTERNAL_SERVICE_ERROR | Request failed due to external service error. |


## 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 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, the most common configurations of the features are provided in terms of profiles, which also can be
selected in the endpoint. A default profile will always be applied if no profile or feature is selected explicitly. In
most cases, consumers don't 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 page 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 needs to be used for any subsequent queries until nextStartAfter is empty. |


**Paging over the whole resource**

The whole resource can be retrieved using an endpoint supporting pagination. The reading loop should include a page read
endpoint call with the `startAfter` property, filled with the content of `nextStartAfter` from the previous page read a
result. When `nextStartAfter` if the property is empty, the reading loop should finish processing.

**Example**


```note
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 different rate limits occur for bulk endpoints.
- Data Mirror: Use continuously running monitors to process your data and distribute workloads.
- 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 the data volume and/or
expected throughput.

| Integration Pattern | Data Volume | Maximum Throughput |
|  --- | --- | --- |
| Transactional | 1 | < 20 per Second |
| Bulk | 2-1000 | > 20 per Second |
| Data Mirror | > 1000 | Realtime |
| Analytical | > 1000 | 5 MB per Second |


## Values characters limit

The length of the single value in the request is limited to **1024** characters.

## Rate Limits

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

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

The following rate limits apply to all endpoints:

| Rate Limit | Reset | Scope |
|  --- | --- | --- |
| 5'000 Requests | Hour | Workspace |
| 2'000 Requests | Hour | User |
| 20 Requests | Second | API Key / User |


For selected endpoints, we have additional limits:

- Bulks: CDQ only allows one bulk of a type (i.e., Lookup or Fetch) to be processed sequentially. Remember that
parallelization is applied on the server side, and parallelization on the client side is not required.


| Rate Limit | Reset | Scope |
|  --- | --- | --- |
| 1 Bulk per Type | After Completion | Workspace |


## Quotas

Quotas control API utilization according to each customer's selected subscription. They help plan resources accordingly
to ensure CDQ can meet service levels.

Please reach out to us if you need to adjust quotas.

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

| Rate Limit | Reset | Scope |
|  --- | --- | --- |
| 50 Jobs | Day | Workspace |
| 100'000 Requests | Month | Organization |


CDQ also defines quotas for access to external data sources:

| Rate Limit | Data Source | Reset | Scope |
|  --- | --- | --- | --- |
| 40'0000 Requests | VIES | Day | Organization |


## 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 |


## Request Size Limiting

**Payload size**

For most CDQ endpoints, the maximum acceptable payload size of the request is 10 MB.

Exceptions from this limit are gathered in the table below:

| Endpoint | Request Size |
|  --- | --- |
| [Upsert Business Partner](/documentation/developer-guidelines)  | 250 MB |


**Upload file size**

The same *Request Size Limit* applies to uploading the file.

- For uploading files `<= 10 MB` read [File Upload](/documentation/instructions/uploading-cvs-xls-data) instruction.
- For uploading files `> 10 MB` read [Request Upload](/documentation/instructions/url-upload) instruction.


## Schema

Blank fields are omitted and not included as null to optimize payload sizes. All timestamps are returned to ISO 8601
format

 Carefully read and follow our integration guideline
[S1: Safe consumption of responses](#implementation). 

## 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**

 The following certificates will be active until July 26, 2025. 

| Domain | Certificate | Signature hash | Valid From | Expires |
|  --- | --- | --- | --- | --- |
| api.cdq.com | [Download](/tls/2025/EC-2025-api_cdq_com.zip) | sha384WithECDSA | 26.07.2025 | 25.07.2026 |
| api.corporate-data-league.ch | [Download](/tls/2025/EC-2025-api_corporate-data-league_ch.zip) | sha384WithECDSA | 26.07.2025 | 25.07.2026 |


 Note that the certificates are renewed every year and need to be updated in your certificate
management system (if available). 

**Certificate Details**

The details of the certificates are as follows:

***api.cdq.com***

|  |  |
|  --- | --- |
| Overall Rating | Grade A |
| Serial Number | 0cc7a0baac03816436a5e6926ac9c8eb |
| Key | EC 384 bits |
| Issuer | DigiCert Global G3 TLS ECC SHA384 2020 CA1 |
| Signature algorithm | SHA384withECDSA |
| CA | DigiCert Global Root G3 |
| Trusted | Mozilla  Apple  Android  Java  Windows |


 According to SSL Labs scoring. 

***api.corporate-data-league.ch***

|  |  |
|  --- | --- |
| Overall Rating | Grade A |
| Serial Number | 09c202ade8c5ba9b0a9a53c840135983 |
| Key | EC 384 bits |
| Issuer | DigiCert Global G3 TLS ECC SHA384 2020 CA1 |
| Signature algorithm | SHA384withECDSA |
| CA | DigiCert Global Root G3 |
| Trusted | Mozilla  Apple  Android  Java  Windows |


 According to SSL Labs scoring. 

**RSA Certificates**

We provide the RSA certificates below for customers who don't support elliptic curve algorithms in their systems.

| Domain | Certificate | Signature hash | Valid From | Expires |
|  --- | --- | --- | --- | --- |
| api.cdq.com | [Download](/tls/2025/RSA-2025-api_cdq_com.zip) | sha256WithRSA | 26.07.2025 | 25.07.2026 |
| api.corporate-data-league.ch | [Download](/tls/2025/RSA-2025-api_corporate-data-league_ch.zip) | sha256WithRSA | 26.07.2025 | 25.07.2026 |


**Certificates in CER format**

Certificates in CER format can be downloaded here:

| Domain | Certificate | Signature hash | Valid From | Expires |
|  --- | --- | --- | --- | --- |
| api.cdq.com | [Download](/tls/2025/RSA-2025-api_cdq_com-CER_extension.zip) | sha384WithECDSA | 26.07.2025 | 25.07.2026 |
| api.corporate-data-league.ch | [Download](/tls/2025/RSA-2025-api_corporate-data-league_ch-CER_extension.zip) | sha384WithECDSA | 26.07.2025 | 25.07.2026 |
| api.cdq.com | [Download](/tls/2025/RSA-2025-api_cdq_com-CER_extension.zip) | sha256WithRSA | 26.07.2025 | 25.07.2026 |
| api.corporate-data-league.ch | [Download](/tls/2025/RSA-2025-api_corporate-data-league_ch-CER_extension.zip) | sha256WithRSA | 26.07.2025 | 25.07.2026 |


**History**

| Domain | Certificate | Signature hash | Valid From | Expires |
|  --- | --- | --- | --- | --- |
| api.cdq.com | [Download](/tls/2024/EC-api_cdq_com.zip) | sha384WithECDSA | 27.07.2024 | 30.07.2025 |
| api.corporate-data-league.ch | [Download](/tls/2024/EC-api_corporate-data-league_ch.zip) | sha384WithECDSA | 27.07.2024 | 30.07.2025 |
| api.cdq.com | [Download](/tls/2024/RSA-api_cdq_com.zip) | sha256WithRSA | 27.07.2024 | 30.07.2025 |
| api.corporate-data-league.ch | [Download](/tls/2024/RSA-api_corporate-data-league_ch.zip) | sha256WithRSA | 27.07.2024 | 30.07.2025 |


## Versioning

**Understanding version numbers**

A version number uniquely identifies each API or App release. The structure of the version follows the standards of
Semantic Versioning 2.0.

Format and example:


```note
<MAJOR>.<MINOR>.0+<BUILD TAG>
25     .45     .0+202007747438
```

- **Major:** Incremented when incompatible API changes are releases
- **Minor:** Incremented when capability or fixes are released in a backwards-compatible manner
- **Build:** Timestamp of the build


Each API or App has its release cycle and thus, its dedicated version. Release notes are published
[here](https://meta.cdq.com).

**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**

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 to provide two versions in parallel. If no
version number is provided, the version is `v1`. Example:


```note
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 offer features and
fixes for the latest and 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 to reference versions quickly.

- **V1, V2, .. ,VX:** Refers to the major version of an API
- **latest:** Refers to the latest version of an API


![](/assets/tags.2b887e02932cc22f65417ad59af8cf276d534e907b801c325f1735ad92466f70.a985b6b7.png)

*Version selector by tags*

**End-of-life**

The end of life for 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 capability 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 integrate the API into their applications and services, allowing for smoother adoption and
transition once the API is officially launched.

  functionalities aren't recommended to be implemented in a production
environment. 

**API Beta Versions**

APIs Beta versions are marked in the dropdown list with the  flag next to the API version.

|  |
|  --- |
| ![](/assets/betaver.5285f7ea0b7b0b3068b1fcabbad0d653d61e92f387c0da767ebed4790831f852.a985b6b7.png) |
| *Version selector with beta flag* |


**Endpoint Beta Versions**

Endpoints Beta versions are marked with  badge in the API documentation next to the endpoint name.

Beta parameters, properties and enums are marked with  badge.

**Parameters, properties and toggle features Beta Versions**

Parameters, properties and toggle features Beta versions are marked with  badge in the API documentation
next to the parameter, property or feature description.

  badges 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

The following guidelines support developers in building rocket-solid client implementations.

**Authorization**

**A1: Token Management** Always uses the latest token for authorization. Tokens are valid for a limited time and must be
refreshed before expiration.


```json
{
  "access_token": "eyJhbG...HSmgnS_0",
  "expires_in": 1800,
  "token_type": "Bearer"
}
```

**Schema**

**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 something similar.

Here's 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 n


```Response1
{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  "lastPaymentDate" : "2021-18-45"
  "country" : "DE"
  ..
}
```


```Response2
{
  "internationalBankIdentifier" : "DE34XXXXXXXXXXXXXXXXX"
  // ATTENTION: field "lastPaymentDate" is null so it will not be part of the response
  "country" : "DE"
  ..
}
```

If your client implementation always requires the field `lastPaymentDate` in every response, then **Response #2** will
lead to an application error, which needs to be avoided.

**S2: Safe consumption of enums** Enumerations provide a fixed set of values for specific fields. Adding additional enum
values is considered a non-breaking change. Your client implementation should be able to handle unknown enum values
gracefully.

If you use OpenAPI Generator to generate skeletons for your implementation, we highly recommend turning on the option
`enumUnknownDefaultCase` in the configuration.

According to the official documentation, "If the server adds new enum cases unknown by an old spec/client, the client
will fail to parse the network response. With this option enabled, each enum will have a new case,
'unknown_default_open_api', so that when the server sends an enum case unknown by the client/spec, they can safely fall
back to it."

## Specifications

CDQ APIs are available via REST or [SOAP 1.2](https://www.w3.org/TR/soap12-part1/#XMLSchemaP2). All specifications are
gather in the table provides links to download CDQ APIs specification in `JSON`, `YAML`, `WSDL` or `WADL` format.

Specifications were moved [here](/documentation/specifications).

## Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!