Skip to content

Collaboration API (1)

CDQ.POOL API for reviews

Download OpenAPI description
api-v1.json
api-v1.yaml
Overview
URL

https://www.cdq.com/about-cdq#cdq-team

Michał Malinka

michal.malinka@cdq.com

Languages
Servers
Mock server

https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/

Production SOAP

https://collaboration-api.reverse-proxy.prod.k8s.production.cdq-cloud-engine.com/soap/v1/

Production

https://collaboration-api.reverse-proxy.prod.k8s.production.cdq-cloud-engine.com/

Sharing

Everything about Business Partners

Operations

Supported Countries

Request

Read countries supported by sharing.

Security
oAuth2
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username.

Example: johndoe
curl -i -X GET \
  https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/sharing/businesspartners/supportedCountries \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Credential-Username: johndoe'

Responses

OK

Bodyapplication/json
countriesArray of objects(SupportedCountry)
Response
application/json
{
  "countries": [
    { … }
  ]
}

Data Mirror Event

Request

Start a sharing process for a BusinessPartner by providing a DataMirrorEvent.

Security
oAuth2
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username.

Example: johndoe
Bodyapplication/jsonrequired
storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
storageOrganizationIdstring(OrganizationId)required

Uniquely identifying ID of the organization.

Example: "cdq_monitor"
businessPartnerIdsArray of strings(BusinessPartnerId)required
Example: ["63e635235c06b7396330fe40"]
userIdstring(UserId)required

Unique ID of a user.

Example: "johndoe"
sharingTargetstring

Destination of the sharing process.

Example: "CDQ.POOL"
curl -i -X POST \
  https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/sharing/businesspartners/dataMirrorEvent \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: johndoe' \
  -d '{
    "storageId": "72d6900fce6b326088f5d9d91049e3e6",
    "storageOrganizationId": "cdq_monitor",
    "businessPartnerIds": [
      "63e635235c06b7396330fe40"
    ],
    "userId": "johndoe",
    "sharingTarget": "CDQ.POOL"
  }'

Responses

OK

Response
No content

Inspect Sharing Status

Request

Inspect the given Business Partner if it can participate in the sharing process. Only for debug purposes.

Security
oAuth2
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username.

Example: johndoe
Bodyapplication/jsonrequired

The Business Partner which will be inspected for its feasibility to participate in sharing process

businessPartnerobject(BusinessPartner)required

An organization which has some degree of involvement with another organization's business dealings. Typically, a company's business partner is another company in the role of a customer, a supplier, a vendor, or a service provider. In the CDL context, the business partner is the core managed entity. A business partner is globally uniquely identifiable by a CDL ID, and all managed information such as addresses, documents, and hierarchies is linked to a business partner.

businessPartner.​idstring

Business Partner identifier within a storage. Autogenerated.

Example: "CH.UIDR:CHE218608886"
businessPartner.​dataSourcestring(BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
businessPartner.​externalIdstring(BusinessPartnerExternalId)

Arbitrary identifier type to mark customer IDs that are "external" from CDQ's perspective. This is the identifier a customer provides to identify its records.

Example: "The ID managed in the customer's SAP systems."
businessPartner.​disclosedboolean

A flag to indicate whether the business partner should participate in the sharing or not. If 'true' this business partner might be used to create a new entry or update an existing entry in the community pool. Otherwise it will not be considered for the sharing process.

Example: "true"
businessPartner.​namesArray of objects(Name)
Example: ["Corporate Data Quality AG"]
businessPartner.​legalFormobject(LegalForm)

The legal form of a business partner/type/legal entity is the form it takes in the eyes of the law governing it. The legal form of a company is the general type it may legally use to identify itself according to the local, regional, national, or international law governing it. This is normally reflected in the ending abbreviation after the company's name (e.g. AG, Inc., LLC, S.A.).

Example: "Aktiengesellschaft"
businessPartner.​identifiersArray of objects(Identifier)
Example: ["VAT identification number"]
businessPartner.​categoriesArray of objects(BusinessPartnerCategory)
Example: ["Hotel"]
businessPartner.​statusobject(BusinessPartnerStatus)

Describes the status of a business partner with respect to its level of activity (e.g. out of business) or legally relevant conditions.

businessPartner.​metadataobject(BusinessPartnerMetadata)

Metadata of a business partner.

businessPartner.​addressesArray of objects(Address)
Example: ["Lukasstraße 4, 9008 St. Gallen"]
businessPartner.​typesArray of objects(BusinessPartnerType)
businessPartner.​recordstring

Stringified JSON of an individual business partner record.

Example: "{json_body}"
businessPartner.​profileobject(PartnerProfile)

A business partner profile contains important information about a company, such as its classification, tags, contact details, or minority indicator.

curl -i -X POST \
  https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/sharing/businesspartners/inspectSharingStatus \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: johndoe' \
  -d '{
    "businessPartner": {
      "id": "CH.UIDR:CHE218608886",
      "dataSource": "648824a691d8d2503d65103e",
      "externalId": "The ID managed in the customer'\''s SAP systems.",
      "disclosed": "true",
      "names": [
        "Corporate Data Quality AG"
      ],
      "legalForm": "Aktiengesellschaft",
      "identifiers": [
        "VAT identification number"
      ],
      "categories": [
        "Hotel"
      ],
      "status": {
        "type": "In Liquidation",
        "officialDenotation": "Good Standing",
        "validFrom": "2022-02-26",
        "validUntil": "2022-02-26"
      },
      "metadata": {
        "status": {
          "recordStatus": "ACCEPTED",
          "explanations": [
            "The business partner record is accepted."
          ]
        },
        "sharingStatus": {
          "status": "SHARED_WITH_NO_MATCH",
          "description": "The business partner record is shared with no match."
        },
        "reason": "The business partner is in liquidation.",
        "identityLinks": [
          {
            "linkId": "8926689",
            "cdqId": "VIES:PL8660001429",
            "addressId": "8926689",
            "externalAddressId": "8926689",
            "status": {
              "details": [
                {}
              ]
            }
          }
        ],
        "logResultStatuses": [
          {
            "processingLogId": "CURATION_LOG",
            "status": "INFO"
          }
        ]
      },
      "addresses": [
        "Lukasstraße 4, 9008 St. Gallen"
      ],
      "types": [
        {
          "name": "Legal Entity",
          "url": "https://meta.cdq.com/Business_partner/type",
          "technicalKey": "LEGAL_ENTITY"
        }
      ],
      "record": "{json_body}",
      "profile": {
        "minorityIndicator": "Social enterprise",
        "classifications": [
          "NAF"
        ],
        "phoneNumbers": [
          "+41 71 571 10 40"
        ],
        "websites": [
          "www.cdq.com"
        ],
        "contactEmails": [
          "developer-portal@cdq.com"
        ],
        "tags": [
          {
            "value": "Warehouse",
            "type": {
              "technicalKey": "WAREHOUSE"
            }
          }
        ]
      }
    }
  }'

Responses

OK

Bodyapplication/json
businessPartnerobject(BusinessPartner)

An organization which has some degree of involvement with another organization's business dealings. Typically, a company's business partner is another company in the role of a customer, a supplier, a vendor, or a service provider. In the CDL context, the business partner is the core managed entity. A business partner is globally uniquely identifiable by a CDL ID, and all managed information such as addresses, documents, and hierarchies is linked to a business partner.

Response
application/json
{
  "businessPartner": {
    "id": "CH.UIDR:CHE218608886",
    "dataSource": "648824a691d8d2503d65103e",
    "externalId": "The ID managed in the customer's SAP systems.",
    "disclosed": "true",
    "names": [ … ],
    "legalForm": "Aktiengesellschaft",
    "identifiers": [ … ],
    "categories": [ … ],
    "status": { … },
    "metadata": { … },
    "addresses": [ … ],
    "types": [ … ],
    "record": "{json_body}",
    "profile": { … }
  }
}

Lookup Business Partner

Request

Lookup business partners in the CDQ Community Pool.

Security
oAuth2
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username.

Example: johndoe
Bodyapplication/jsonrequired

request

storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
businessPartnerIdstring(BusinessPartnerId)required

A CDQ ID identifies a business partner uniquely in the context of the Corporate Data League.

Example: "63e635235c06b7396330fe40"
businessPartnerobject(BusinessPartner)

An organization which has some degree of involvement with another organization's business dealings. Typically, a company's business partner is another company in the role of a customer, a supplier, a vendor, or a service provider. In the CDL context, the business partner is the core managed entity. A business partner is globally uniquely identifiable by a CDL ID, and all managed information such as addresses, documents, and hierarchies is linked to a business partner.

curl -i -X POST \
  https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/sharing/businesspartners/lookup \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: johndoe' \
  -d '{
    "storageId": "72d6900fce6b326088f5d9d91049e3e6",
    "businessPartnerId": "63e635235c06b7396330fe40",
    "businessPartner": {
      "id": "CH.UIDR:CHE218608886",
      "dataSource": "648824a691d8d2503d65103e",
      "externalId": "The ID managed in the customer'\''s SAP systems.",
      "disclosed": "true",
      "names": [
        "Corporate Data Quality AG"
      ],
      "legalForm": "Aktiengesellschaft",
      "identifiers": [
        "VAT identification number"
      ],
      "categories": [
        "Hotel"
      ],
      "status": {
        "type": "In Liquidation",
        "officialDenotation": "Good Standing",
        "validFrom": "2022-02-26",
        "validUntil": "2022-02-26"
      },
      "metadata": {
        "status": {
          "recordStatus": "ACCEPTED",
          "explanations": [
            "The business partner record is accepted."
          ]
        },
        "sharingStatus": {
          "status": "SHARED_WITH_NO_MATCH",
          "description": "The business partner record is shared with no match."
        },
        "reason": "The business partner is in liquidation.",
        "identityLinks": [
          {
            "linkId": "8926689",
            "cdqId": "VIES:PL8660001429",
            "addressId": "8926689",
            "externalAddressId": "8926689",
            "status": {
              "details": [
                {}
              ]
            }
          }
        ],
        "logResultStatuses": [
          {
            "processingLogId": "CURATION_LOG",
            "status": "INFO"
          }
        ]
      },
      "addresses": [
        "Lukasstraße 4, 9008 St. Gallen"
      ],
      "types": [
        {
          "name": "Legal Entity",
          "url": "https://meta.cdq.com/Business_partner/type",
          "technicalKey": "LEGAL_ENTITY"
        }
      ],
      "record": "{json_body}",
      "profile": {
        "minorityIndicator": "Social enterprise",
        "classifications": [
          "NAF"
        ],
        "phoneNumbers": [
          "+41 71 571 10 40"
        ],
        "websites": [
          "www.cdq.com"
        ],
        "contactEmails": [
          "developer-portal@cdq.com"
        ],
        "tags": [
          {
            "value": "Warehouse",
            "type": {
              "technicalKey": "WAREHOUSE"
            }
          }
        ]
      }
    }
  }'

Responses

OK

Bodyapplication/json
totalinteger

Total number of found candidates.

Example: "10"
valuesArray of objects(BusinessPartnerLookupMatch)
debugInfoobject

Debug information related to result of searching sharing candidates.

Response
application/json
{
  "total": "10",
  "values": [
    { … }
  ],
  "debugInfo": {
    "request": { … }
  }
}

Link Business Partner

Request

Link business partner with the CDQ Community Pool. Only business partner which is in status PENDING_LINKAGE_DECISION is allowed.

In successful case, execution finishes in the following states: | Review decision | Sharing status | | NO_MATCH | SHARED_WITH_NO_MATCH_BY_REVIEW | | LINK | SHARED_BY_REVIEW | | LINK_AND_SEND_UPDATE | SHARED_BY_REVIEW |

status field is OK in case of successful linkage or FAILED in case of failure. message field presents the reason of failure.

In case the business partner contents has been changed, the status can be different and will be visible in the result.

Security
oAuth2
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username.

Example: johndoe
Bodyapplication/jsonrequired

request

decisionstring(ReviewDecisionParam)required

Sharing process review decision.

Enum ValueDescription
NO_MATCH

Customer decision that no candidate out of provided candidates matches to customerBusinessPartner. Leads to creation of a new business partner in the sharing pool. cdqId field is not allowed in this decision.

LINK

Customer decision that candidate identified by cdqId out of provided candidates matches to customerBusinessPartner. Leads to link creation between customerBusinessPartner and candidate from sharing pool. No seed update is generated. cdqId field is mandatory in this decision.

LINK_AND_SEND_UPDATE

Customer decision that candidate identified by cdqId out of provided candidates matches to customerBusinessPartner. Leads to link creation between customerBusinessPartner and candidate from sharing pool. Seed update is generated. cdqId field is mandatory in this decision.

Example: "LINK_AND_SEND_UPDATE"
cdqIdstring(ProvenanceCdqId)

The ID provided for a linkage with the source by CDQ.

Example: "VIES:PL8660001429"
storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
customerBusinessPartnerobject(ReviewDecisionBusinessPartner)required

ID of a business partner within storage identified by storageId for which the decision is made.

customerBusinessPartner.​idstring(BusinessPartnerId)required

A CDQ ID identifies a business partner uniquely in the context of the Corporate Data League.

Example: "63e635235c06b7396330fe40"
curl -i -X POST \
  https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/sharing/reviewdecisions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: johndoe' \
  -d '{
    "decision": "LINK_AND_SEND_UPDATE",
    "cdqId": "VIES:PL8660001429",
    "storageId": "72d6900fce6b326088f5d9d91049e3e6",
    "customerBusinessPartner": {
      "id": "63e635235c06b7396330fe40"
    }
  }'

Responses

OK

Bodyapplication/json
cdqIdstring(ProvenanceCdqId)

The ID provided for a linkage with the source by CDQ.

Example: "VIES:PL8660001429"
sharingStatusstring

Sharing status of the reviewed business partner.

Sharing status possible values:

  • UNDER_CONSIDERATION
  • UNDER_CONSIDERATION_COUNTRY
  • UNDER_CONSIDERATION_NOT_VALIDATED
  • UNDER_CONSIDERATION_MISSING_MATCH_TYPE
  • UNDISCLOSED_RECORD
  • MISSING_INFORMATION_FOR_LINKAGE
  • ERRONEOUS_INFORMATION_FOR_LINKAGE
  • ERRONEOUS_RECORD
  • SHARED_WITH_NO_MATCH_BY_REVIEW
  • SHARED_BY_REVIEW
  • PROCESS_ISSUE

Never reached statuses in this endpoint:

  • PENDING_LINKAGE_DECISION
  • SHARED_WITH_NO_MATCH
  • SHARED_WITH_CONFIDENT_MATCH
Example: "UNDER_CONSIDERATION"
statusstring

Status possible values:

  • OK - successfully shared.
  • FAILED - failed to share. See message field for details.
Example: "OK"
messagestring

Message describing the result of the review decision.

Example: "Sharing successful."
debugInfoobject

Debug information about the result of the review decision.

Response
application/json
{
  "cdqId": "VIES:PL8660001429",
  "sharingStatus": "UNDER_CONSIDERATION",
  "status": "OK",
  "message": "Sharing successful.",
  "debugInfo": {
    "request": { … }
  }
}

Update system API keys for Quality Gate (dev only)

Request

Update the system API keys locally for development environment.

Security
oAuth2
Bodyapplication/jsonrequired
legalEntityClientIdstring(LegalEntityClientId)

Legal entity client ID.

Example: "a23fe456-7890-bcde-f123-456789abcdef"
operationalEntityClientIdstring(OperationalEntityClientId)

Operational entity client ID.

Example: "a23fe456-7890-bcde-f123-456789"
organizationalUnitClientIdstring(OrganizationalUnitClientId)

Organizational unit client ID.

Example: "a23fe456-7890-bcde-f123-456789abcdef"
curl -i -X PATCH \
  https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/sharing/systemApiKeys/dev \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "legalEntityClientId": "a23fe456-7890-bcde-f123-456789abcdef",
    "operationalEntityClientId": "a23fe456-7890-bcde-f123-456789",
    "organizationalUnitClientId": "a23fe456-7890-bcde-f123-456789abcdef"
  }'

Responses

OK

Bodyapplication/json
legalEntityClientIdstring(LegalEntityClientId)

Legal entity client ID.

Example: "a23fe456-7890-bcde-f123-456789abcdef"
operationalEntityClientIdstring(OperationalEntityClientId)

Operational entity client ID.

Example: "a23fe456-7890-bcde-f123-456789"
organizationalUnitClientIdstring(OrganizationalUnitClientId)

Organizational unit client ID.

Example: "a23fe456-7890-bcde-f123-456789abcdef"
Response
application/json
{
  "legalEntityClientId": "a23fe456-7890-bcde-f123-456789abcdef",
  "operationalEntityClientId": "a23fe456-7890-bcde-f123-456789",
  "organizationalUnitClientId": "a23fe456-7890-bcde-f123-456789abcdef"
}

Read system API keys for Quality Gate (dev only)

Request

Read the system API keys locally for development environment.

Security
oAuth2
curl -i -X GET \
  https://idp.cdq.com/_mock/apis/collaboration-api/api-v1/sharing/systemApiKeys/dev \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
legalEntityClientIdstring(LegalEntityClientId)

Legal entity client ID.

Example: "a23fe456-7890-bcde-f123-456789abcdef"
operationalEntityClientIdstring(OperationalEntityClientId)

Operational entity client ID.

Example: "a23fe456-7890-bcde-f123-456789"
organizationalUnitClientIdstring(OrganizationalUnitClientId)

Organizational unit client ID.

Example: "a23fe456-7890-bcde-f123-456789abcdef"
Response
application/json
{
  "legalEntityClientId": "a23fe456-7890-bcde-f123-456789abcdef",
  "operationalEntityClientId": "a23fe456-7890-bcde-f123-456789",
  "organizationalUnitClientId": "a23fe456-7890-bcde-f123-456789abcdef"
}

Matching

Everything about Business Partners

Reviews

Collaborative review of Business Partner updates

Maintenance

Operations

Cache

Operations