Companies API

Companies
 3.7.0 
OAS3

Introduction

The Company API can be used to create, modify and update Company information within the dealer management systems.

This resource is typically used to achieve outcomes around improving communication by customer facing staff and maintenance of accurate data within DMS

Definitions

The following definitions are referenced in this API

Customer - a customer is an individual (a single person) contained within a dealer management system. Customers are maintianed via the customers end-point.
Company - a company is an organization contained within a dealer management system.

HTTP header parameters

  • x-onbehalf-of
    The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system. This user ID will be used in the backend system for auditing reasons.

  • correlation-id
    A unique identifier value (GUID) that is attached to requests and messages that allow reference to a particular transaction or event chain. This ID might be required in case a support case is logged.

Change history

[3.7.0] (14-03-2022)

  • Updated CustomerCompanyShared references

[3.6.0] (10-02-2022)

  • Added support of data channels in the privacy statements (MIDWARE-2846)

[3.5.0] (17-06-2021)

  • Added pagination to VehicleLinks (MIDWARE-2660)
  • Added pagination to companies privacies
  • Added comment to GET company vehicles opject, limitation to 50.
  • Added Keyloop URL's

[3.4.2] (28-05-2021)

  • Updated mail address

[3.4.1] (22-04-2021)

  • Change to Keyloop

[3.4.0] (16-04-2021)

  • Add second company name and website (MIDWARE-2485)

Version 3.3.0 (22-03-2021)

  • Company Type of Business added (MIDWARE-2369)

Version 3.2.0 (16-11-2020)

  • Flexible number of channels in GET privacy statements (MIDWARE-2354)

Version 3.1.0 (29-09-2020)

  • Remove supplementaryData 'PRIVACY' from GET company by ID [MIDWARE-2263]

Version 3.0.0 (25-08-2020)

  • Refactor company API [MIDWARE-1837]


Servers
Computed URL:https://api.eu-stage.keyloop.io/sample/sample/v3

Server variables

enterpriseIdstoreId
enterpriseId
storeId

Company

Common company methods

GET​/companies
Company Search

Search for companies using the filter criteria specified within the query parameters - at least one search parameter must be specified.

Parameters

NameDescription
freeTextSearch
string
(query)

Free text to search against multiple fields on the customer's details. This filter will be used to search companies who either have this free text in name or address or phone or postalCode or email.

name
string
(query)

Company name filter

email
string
(query)

Email filter

phone
string
(query)

Phone filter

postalCode
string
(query)

Postal code
(Should be used with at least one of the other query parameters)

taxRegistration
string
(query)

Tax registration filter

reference
string
(query)

The reference is the id of the company that will typically be shown in applications.

page
integer
(query)

A non-zero integer representing the page of the results

Default value : 1

Examples:
pageSize
integer
(query)

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Default value : 50

Examples:

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "companies": [
    {
      "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac",
      "reference": 10789,
      "name": "Company Ltd.",
      "address": "7 Mill Lane, London, SE4 1UU",
      "communications": {
        "mainPhone": "111-234567",
        "otherPhone": "111-234599",
        "fax": "111-255666",
        "email": "info@something.com"
      },
      "links": [
        {
          "method": "GET",
          "rel": "self",
          "href": "string",
          "title": "string"
        }
      ]
    }
  ],
  "totalItems": 4,
  "totalPages": 1,
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
400

Bad request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
POST​/companies
Create Company

Use this endpoint to create a customer record within the CDK database.

Parameters

NameDescription
x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

Company

{
  "languageCode": "en-GB",
  "organization": {
    "name": "Company Ltd.",
    "name2": "Car trading business",
    "taxRegistration": "1234-1234",
    "businessRegistration": "1234-1234",
    "governmentRegistration": "1234-1234",
    "typeOfBusinessCode": "AU",
    "website": "http://www.company.com"
  },
  "addresses": {
    "physical": {
      "streetType": "Avenue",
      "streetName": "Mill Lane",
      "houseNumber": 7,
      "buildingName": "string",
      "floorNumber": "string",
      "doorNumber": "string",
      "blockName": "string",
      "estate": "string",
      "postalCode": "SE4 1UU",
      "suburb": "string",
      "city": "London",
      "county": "string",
      "province": "string",
      "countryCode": "GB"
    },
    "postal": {
      "poBoxName": "string",
      "poBoxNumber": 12,
      "poBoxSuite": "string",
      "postalCode": "string",
      "suburb": "string",
      "city": "string",
      "county": "string",
      "province": "string",
      "countryCode": "GB"
    }
  },
  "communications": {
    "mainPhone": "111-234567",
    "otherPhone": "111-234599",
    "fax": "111-255666",
    "email": "info@something.com"
  }
}

Responses

CodeDescriptionLinks
201

Created

Media type
Controls Accept header.
{
  "company": {
    "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac",
    "reference": 10789,
    "status": "CUSTOMER",
    "languageCode": "en-GB",
    "organization": {
      "name": "Company Ltd.",
      "name2": "Car trading business",
      "taxRegistration": "1234-1234",
      "businessRegistration": "1234-1234",
      "governmentRegistration": "1234-1234",
      "typeOfBusiness": {
        "code": "AU",
        "description": "Automotive"
      },
      "website": "http://www.company.com"
    },
    "addresses": {
      "physical": {
        "streetType": "Avenue",
        "streetName": "Mill Lane",
        "houseNumber": 7,
        "buildingName": "string",
        "floorNumber": "string",
        "doorNumber": "string",
        "blockName": "string",
        "estate": "string",
        "postalCode": "SE4 1UU",
        "suburb": "string",
        "city": "London",
        "county": "string",
        "province": "string",
        "countryCode": "GB",
        "formattedAddress": {
          "line1": "10 Downing Street",
          "line2": "Apartment 278",
          "line3": "XY14 2LG LONDON",
          "line4": "United Kingdom",
          "line5": null
        }
      },
      "postal": {
        "poBoxName": "string",
        "poBoxNumber": 12,
        "poBoxSuite": "string",
        "postalCode": "string",
        "suburb": "string",
        "city": "string",
        "county": "string",
        "province": "string",
        "countryCode": "GB",
        "formattedAddress": {
          "line1": "10 Downing Street",
          "line2": "Apartment 278",
          "line3": "XY14 2LG LONDON",
          "line4": "United Kingdom",
          "line5": null
        }
      }
    },
    "communications": {
      "mainPhone": "111-234567",
      "otherPhone": "111-234599",
      "fax": "111-255666",
      "email": "info@something.com"
    },
    "vehicles": [
      {
        "relationship": "REGISTEREDKEEPER",
        "vehicle": {
          "vehicleId": "00000000-0000-0000-0000-000000000000",
          "reference": 10234,
          "class": "CAR",
          "makeId": "FORD",
          "description": "Ford F 250",
          "vin": "1FTHF25H1JNB79097",
          "licensePlate": "TOY-123"
        }
      }
    ],
    "relations": {
      "customers": [
        {
          "customerId": "781aa0d6-a540-4e4d-a121-2997bcb0b9bd",
          "reference": 10345,
          "name": "Mr. Joe Doe",
          "address": "7 Mill Lane, London, SE4 1UU"
        }
      ],
      "companies": [
        {
          "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac",
          "reference": 10789,
          "name": "Company Ltd.",
          "address": "7 Mill Lane, London, SE4 1UU"
        }
      ]
    },
    "updateHistory": {
      "created": "2008-09-15T15:53:00.000Z",
      "lastModified": "2008-09-15T15:53:00.000Z"
    }
  },
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
400

Bad request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
GET​/companies​/{companyId}
Get Company

Retrieve a company resource for a given {companyId}

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

supplementaryData
array[string]
(query)

Suplementary data to be included in the response

Available values : RELATIONS, VEHICLELINK

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "company": {
    "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac",
    "reference": 10789,
    "status": "CUSTOMER",
    "languageCode": "en-GB",
    "organization": {
      "name": "Company Ltd.",
      "name2": "Car trading business",
      "taxRegistration": "1234-1234",
      "businessRegistration": "1234-1234",
      "governmentRegistration": "1234-1234",
      "typeOfBusiness": {
        "code": "AU",
        "description": "Automotive"
      },
      "website": "http://www.company.com"
    },
    "addresses": {
      "physical": {
        "streetType": "Avenue",
        "streetName": "Mill Lane",
        "houseNumber": 7,
        "buildingName": "string",
        "floorNumber": "string",
        "doorNumber": "string",
        "blockName": "string",
        "estate": "string",
        "postalCode": "SE4 1UU",
        "suburb": "string",
        "city": "London",
        "county": "string",
        "province": "string",
        "countryCode": "GB",
        "formattedAddress": {
          "line1": "10 Downing Street",
          "line2": "Apartment 278",
          "line3": "XY14 2LG LONDON",
          "line4": "United Kingdom",
          "line5": null
        }
      },
      "postal": {
        "poBoxName": "string",
        "poBoxNumber": 12,
        "poBoxSuite": "string",
        "postalCode": "string",
        "suburb": "string",
        "city": "string",
        "county": "string",
        "province": "string",
        "countryCode": "GB",
        "formattedAddress": {
          "line1": "10 Downing Street",
          "line2": "Apartment 278",
          "line3": "XY14 2LG LONDON",
          "line4": "United Kingdom",
          "line5": null
        }
      }
    },
    "communications": {
      "mainPhone": "111-234567",
      "otherPhone": "111-234599",
      "fax": "111-255666",
      "email": "info@something.com"
    },
    "vehicles": [
      {
        "relationship": "REGISTEREDKEEPER",
        "vehicle": {
          "vehicleId": "00000000-0000-0000-0000-000000000000",
          "reference": 10234,
          "class": "CAR",
          "makeId": "FORD",
          "description": "Ford F 250",
          "vin": "1FTHF25H1JNB79097",
          "licensePlate": "TOY-123"
        }
      }
    ],
    "relations": {
      "customers": [
        {
          "customerId": "781aa0d6-a540-4e4d-a121-2997bcb0b9bd",
          "reference": 10345,
          "name": "Mr. Joe Doe",
          "address": "7 Mill Lane, London, SE4 1UU"
        }
      ],
      "companies": [
        {
          "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac",
          "reference": 10789,
          "name": "Company Ltd.",
          "address": "7 Mill Lane, London, SE4 1UU"
        }
      ]
    },
    "updateHistory": {
      "created": "2008-09-15T15:53:00.000Z",
      "lastModified": "2008-09-15T15:53:00.000Z"
    }
  },
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
PATCH​/companies​/{companyId}
Update base details as name and communication details of the company

Update company object

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

Company base details

{
  "languageCode": "en-GB",
  "organization": {
    "name": "Company Ltd.",
    "name2": "Car trading business",
    "taxRegistration": "1234-1234",
    "businessRegistration": "1234-1234",
    "governmentRegistration": "1234-1234",
    "typeOfBusinessCode": "AU",
    "website": "http://www.company.com"
  },
  "communications": {
    "mainPhone": "111-234567",
    "otherPhone": "111-234599",
    "fax": "111-255666",
    "email": "info@something.com"
  }
}

Responses

CodeDescriptionLinks
204

No Content

No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
PUT​/companies​/{companyId}​/address
Update Company Address

Update address details for a company object

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

Address object

{
  "physical": {
    "streetType": "Avenue",
    "streetName": "Mill Lane",
    "houseNumber": 7,
    "buildingName": "string",
    "floorNumber": "string",
    "doorNumber": "string",
    "blockName": "string",
    "estate": "string",
    "postalCode": "SE4 1UU",
    "suburb": "string",
    "city": "London",
    "county": "string",
    "province": "string",
    "countryCode": "GB"
  },
  "postal": {
    "poBoxName": "string",
    "poBoxNumber": 12,
    "poBoxSuite": "string",
    "postalCode": "string",
    "suburb": "string",
    "city": "string",
    "county": "string",
    "province": "string",
    "countryCode": "GB"
  }
}

Responses

CodeDescriptionLinks
204

No Content

No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
GET​/companies​/{companyId}​/vehicles
Company Vehicles

Retrieve company vehicle list for a given {companyId}

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

page
integer
(query)

A non-zero integer representing the page of the results

Default value : 1

Examples:
pageSize
integer
(query)

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Default value : 50

Examples:

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "vehicles": [
    {
      "relationship": "REGISTEREDKEEPER",
      "vehicle": {
        "vehicleId": "00000000-0000-0000-0000-000000000000",
        "reference": 10234,
        "class": "CAR",
        "makeId": "FORD",
        "description": "Ford F 250",
        "vin": "1FTHF25H1JNB79097",
        "licensePlate": "TOY-123"
      }
    }
  ],
  "totalItems": 4,
  "totalPages": 1,
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links

Privacy

Company privacy information

GET​/companies​/privacyStatements
Get company privacy statements

Get company privacy statements.

Parameters

NameDescription
page
integer
(query)

A non-zero integer representing the page of the results

Default value : 1

Examples:
pageSize
integer
(query)

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Default value : 50

Examples:

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "privacyStatements": [
    {
      "privacyStatementId": "43b63d31-70754-f48a7-0fc0-057668769c",
      "level": "OEM",
      "providerName": "OEM Name",
      "statementDescription": "OEM statement",
      "channels": [
        "EMAIL"
      ],
      "dataChannels": [
        {
          "code": "IN-CAR",
          "description": "In car analytics"
        }
      ]
    }
  ],
  "totalItems": 4,
  "totalPages": 1,
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
POST​/companies​/{companyId}​/privacies
Create Company Privacy agreement

Create privacy information for a company object

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

Company privacies

{
  "privacyStatementId": "43b63d31-70754-f48a7-0fc0-057668769c",
  "description": "Some description",
  "validFrom": "2019-01-01T00:00:00.000Z",
  "validUntil": "2019-12-31T00:00:00.000Z",
  "channel": {
    "post": "AGREED",
    "email": "DENIED",
    "phone": "UNKNOWN",
    "messaging": "UNKNOWN"
  },
  "dataChannels": [
    {
      "code": "IN-CAR",
      "status": "UNKNOWN"
    }
  ]
}

Responses

CodeDescriptionLinks
201

Created

Media type
Controls Accept header.
{
  "privacy": {
    "privacyId": "462fef0c-ee4c-4d38-843a-0625db1d37b2",
    "privacyStatement": {
      "privacyStatementId": "43b63d31-70754-f48a7-0fc0-057668769c",
      "level": "OEM",
      "providerName": "OEM Name",
      "statementDescription": "OEM statement"
    },
    "description": "Some description",
    "validFrom": "2019-01-01T00:00:00.000Z",
    "validUntil": "2019-12-31T00:00:00.000Z",
    "updateHistory": {
      "created": "2008-09-15T15:53:00.000Z",
      "lastModified": "2008-09-15T15:53:00.000Z"
    },
    "channel": {
      "post": "AGREED",
      "email": "DENIED",
      "phone": "UNKNOWN",
      "messaging": "UNKNOWN"
    },
    "dataChannels": [
      {
        "code": "IN-CAR",
        "description": "In car analytics",
        "status": "UNKNOWN"
      }
    ]
  },
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
GET​/companies​/{companyId}​/privacies
Company Privacy

Retrieve a company privacy object list for a given {companyrId}

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

page
integer
(query)

A non-zero integer representing the page of the results

Default value : 1

Examples:
pageSize
integer
(query)

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Default value : 50

Examples:

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "privacies": [
    {
      "privacyId": "462fef0c-ee4c-4d38-843a-0625db1d37b2",
      "privacyStatement": {
        "privacyStatementId": "43b63d31-70754-f48a7-0fc0-057668769c",
        "level": "OEM",
        "providerName": "OEM Name",
        "statementDescription": "OEM statement"
      },
      "description": "Some description",
      "validFrom": "2019-01-01T00:00:00.000Z",
      "validUntil": "2019-12-31T00:00:00.000Z",
      "updateHistory": {
        "created": "2008-09-15T15:53:00.000Z",
        "lastModified": "2008-09-15T15:53:00.000Z"
      },
      "channel": {
        "post": "AGREED",
        "email": "DENIED",
        "phone": "UNKNOWN",
        "messaging": "UNKNOWN"
      },
      "dataChannels": [
        {
          "code": "IN-CAR",
          "description": "In car analytics",
          "status": "UNKNOWN"
        }
      ]
    }
  ],
  "totalItems": 4,
  "totalPages": 1,
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
PUT​/companies​/{companyId}​/privacies​/{privacyId}
Update Company Privacy

Update privacy information for a company object

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

privacyId *
string
(path)

A unique id that identifies an individual Privacy resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

Company privacies

{
  "description": "Some description",
  "validUntil": "2019-12-31T00:00:00.000Z",
  "channel": {
    "post": "AGREED",
    "email": "DENIED",
    "phone": "UNKNOWN",
    "messaging": "UNKNOWN"
  },
  "dataChannels": [
    {
      "code": "IN-CAR",
      "status": "UNKNOWN"
    }
  ]
}

Responses

CodeDescriptionLinks
204

No Content

No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links

Relations

Customer and company relations

GET​/companies​/{companyId}​/relations
Get relations

Get relations between this company to other individuals and companies

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "customers": [
    {
      "customerId": "781aa0d6-a540-4e4d-a121-2997bcb0b9bd",
      "reference": 10345,
      "name": "Mr. Joe Doe",
      "address": "7 Mill Lane, London, SE4 1UU"
    }
  ],
  "companies": [
    {
      "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac",
      "reference": 10789,
      "name": "Company Ltd.",
      "address": "7 Mill Lane, London, SE4 1UU"
    }
  ]
}
No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
POST​/companies​/{companyId}​/company-relation
Add a link to a company

Add link to another company identified by the company Id.

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

Add company link request

{
  "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac"
}

Responses

CodeDescriptionLinks
204

No Content

No links
400

Bad request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
409

Conflict
A relation to the company identiefied by companyId is already existing

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
DELETE​/companies​/{companyId}​/company-relation​/{relatedCompanyId}
Remove company link another company

Remove link to a company

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

relatedCompanyId *
string
(path)

A unique id that identifies an Company resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Responses

CodeDescriptionLinks
204

No Content

No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links

External references

Company external references

GET​/companies​/external-references
Company Search by external reference

Search for companies based on an external reference identiefied by the providerCode, applicationCode and the externalReference.

Parameters

NameDescription
providerCode *
string
(query)

Generic code of the provider of the application

applicationCode *
string
(query)

Generic code identifying of the providers application

externalReference *
string
(query)

Application specific reference of the individual

page
integer
(query)

A non-zero integer representing the page of the results

Default value : 1

Examples:
pageSize
integer
(query)

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Default value : 50

Examples:

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "companies": [
    {
      "companyId": "991aa0d6-a540-4e4d-a121-2997bcb0b9ac",
      "reference": 10789,
      "name": "Company Ltd.",
      "address": "7 Mill Lane, London, SE4 1UU",
      "communications": {
        "mainPhone": "111-234567",
        "otherPhone": "111-234599",
        "fax": "111-255666",
        "email": "info@something.com"
      },
      "links": [
        {
          "method": "GET",
          "rel": "self",
          "href": "string",
          "title": "string"
        }
      ]
    }
  ],
  "totalItems": 4,
  "totalPages": 1,
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links
POST​/companies​/{companyId}​/external-references
Create External Reference

Use this endpoint to create an external reference for the external party's system identified by the providerCode and applicationCode.

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

External reference

{
  "providerCode": "MERCEDES-BENZ",
  "applicationCode": "TESTAPP",
  "value": 123456
}

Responses

CodeDescriptionLinks
204

No Content

No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
409

Conflict
External reference with providerCode and applicationCode is already existing

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
GET​/companies​/{companyId}​/external-references
Company external references

Retrieve company external reference list for a given companyId

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

providerCode
string
(query)

Generic code of the provider of the application

applicationCode
string
(query)

Generic code identifying of the providers application. Can only be used in combination with the providerCode.

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "references": [
    {
      "providerCode": "MERCEDES-BENZ",
      "applicationCode": "TESTAPP",
      "value": 123456
    }
  ]
}
No links
404

Not Found

No links
PUT​/companies​/{companyId}​/external-references
Update External Reference

Use this endpoint to update the external reference for the external party's system identified by the providerCode and applicationCode.

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Request body

External reference

{
  "providerCode": "MERCEDES-BENZ",
  "applicationCode": "TESTAPP",
  "value": 123456
}

Responses

CodeDescriptionLinks
204

No Content

No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links
451

Unavailable For Legal Reasons
Access to the company data has been restricted for legal reasons, e.g. request ot be forgotten.

No links
DELETE​/companies​/{companyId}​/external-references
Delete External Reference

Use this endpoint to delete the external reference for the external party's system contained within the Company identified by the /Companies endpoint

Parameters

NameDescription
companyId *
string
(path)

A unique id that identifies an individual Company resource.

providerCode *
string
(query)

Generic code of the provider of the application

applicationCode *
string
(query)

Generic code identifying of the providers application

x-on-behalf-of
string
(header)

The user (id) of the user who is actually using this resource. This user Id should be known in the receiving system.

Responses

CodeDescriptionLinks
204

No Content

No links
400

Bad Request

Media type
{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message": "Invalid request",
  "details": [
    {
      "field": "Status",
      "value": "string",
      "issue": "The value 'XYZ' is not valid."
    }
  ],
  "links": [
    {
      "method": "GET",
      "rel": "self",
      "href": "string",
      "title": "string"
    }
  ]
}
No links
404

Not Found

No links

Reference data

Reference data

GET​/companies​/type-of-businesses
Search type of business codes

Search type of business codes

Parameters

NameDescription
Description
string
(query)

Type of business description

page
integer
(query)

A non-zero integer representing the page of the results

Default value : 1

Examples:
pageSize
integer
(query)

A non-negative, non-zero integer indicating the maximum number of results to return at one time

Default value : 50

Examples:

Responses

CodeDescriptionLinks
200

Success

Media type
Controls Accept header.
{
  "typeOfBusinesses": [
    {
      "code": "AU",
      "description": "Automotive"
    }
  ],
  "totalItems": 4,
  "totalPages": 1,
  "links": {
    "method": "GET",
    "rel": "self",
    "href": "string",
    "title": "string"
  }
}
No links

Schemas

Company Search Response
Company create request
Company create response
Company Query Response
Company Update Request
Privacy statements Search response
Privacy agreeements Search response
Privacy create response
Company relations response
Add company relation
Company Type of Business Response
Company Simple Reference
Organization Details
Organization Details
Company address
Company address
CompanyCommunication
Company
Customer and company relations
Supplementary data
Company status
Tax registration number
Business registration number
Government registration number
Type of business that the company is involved with
Type of business code
Preferred language code
CompanyLandline
CompanyOtherPhone
CompanyFax
CompanyEmail
ValidationError
Common.Response.Error
Common.Response.Collection
Common.Response.Single
Common.Address.Physical
Common.Address.Postal
Update History
Privacy agreement create request
Privacy agreement udate request
External reference search result
Company to customer relation details
Company relation details
Privacy statement definition
Privacy statement agreement
External reference
CustomerCompany.FormattedAddress
Company Id
Company address
Reference
Company full name
Company second name
Company website