Administration API [ version1.1.0 ]

The Administration API allows you to manage your Tenants and Companies. An example Postman Collection containing these enpoints can be found on Github.

Base URI: https://administration.unite.services/api

Legal Disclaimer

The Unite Developer Documentation and the APIs made available by Unite Network SE (“Unite”) are provided solely at the discretion of Unite without warranty of any kind, and Unite may change, suspend, or cancel any or all features or functions of the Unite APIs or revise the web site at any time. Any production use of or commercialization of applications containing any Unite APIs is prohibited without a written agreement between your company and Unite governing such activities.

Access to the Unite APIs is available to you as a Unite Partner Agreement and the Unite Terms of Use respectively. Use of the Unite APIs is purely optional and is subject to restrictions stated in the API documentation and the API Terms of Use as contained in Part D of the Unite Terms of Use and the documentation found below. If you wish to connect a third-party service using any Unite API, first confirm that the company is participating in the Unite API partner program and is authorized to provide connection to this solution using a Unite API. You will be required to submit written consent to Unite to authorize the exchange of data with the third-party service.

Common Headers

For an overview of common headers, see here.

Technical Disclaimer

This REST API follows the HATEOAS design principle. The link URLs contained in the documentation or the Postman Collection reflect the current state of the API, but may be changed without further notice. A client should not rely on these URLs to remain stable. Instead, it should follow the links contained in the resources to ensure that client server interaction will not break across releases.

Changelog

Please find the changelog of this api here.

/

Entry point for accessing the Administration API

get

get

This is the main entry point into the Administration API

This is the main entry point into the Administration API

Secured by Tenant Administration API Token

HTTP status code 200

Returns an array of HATEOAS links to manage Tenant and Company Resources

Body

Media type: application/vnd.mercateo-unite.administration.v1+json

Type: base.DefaultRoot

{
  "tenantId": "c27b16da-30b1-482e-b14f-ec6754bdbb75",
  "_schema": {
    "links": [
      {
        "href": "https://administration.unite.services/api/tenant",
        "method": "GET",
        "rel": "tenant-root"
      }
    ]
  }
}

HTTP status code 401

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
    "status": 401,
    "title": "Unauthorized",
    "detail": "Unauthorized"
}

HTTP status code 405

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 405,
  "title": "Method Not Allowed",
  "detail": "HTTP 405 Method Not Allowed"
}

HTTP status code 406

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 406,
  "title": "Not Acceptable",
  "detail": "Not Acceptable, doesn't include valid version, see valid versions here: https://portal.unite.eu/developers/apis/administration-api"
}

Secured by Tenant Administration API Token

Headers

  • Authorization : required (string)

    Endpoint expects an Authorization header containing a token for the Tenant Administration API using the Bearer schema.

    A token for the Tenant Administration API has its audience set to https://unite.eu/tenant-administration-api.

    Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL3VuaXRlLmV1L3RlbmFudF9pZCI6IjExMTExMTExLTExMTEtMTExMS0xMTExLTExMTExMTExMTExMSIsImh0dHBzOi8vdW5pdGUuZXUvY29tcGFueV9pZCI6IjIyMjIyMjIyLTIyMjItMjIyMi0yMjIyLTIyMjIyMjIyMjIyMiIsImh0dHBzOi8vdW5pdGUuZXUvZW1wbG95ZWVfaWQiOiIzMzMzMzMzMy0zMzMzLTMzMzMtMzMzMy0zMzMzMzMzMzMzMzMiLCJpc3MiOiJzZWxmLWlzc3VlZCIsInN1YiI6InN1YmplY3QiLCJhdWQiOiJodHRwczovL3VuaXRlLmV1L2FwaSIsInNjb3BlIjoib2ZmbGluZV9hY2Nlc3MifQ.VetLahLfqaRD5_sDEMgEYIxTyWmPUY-YuTlHLQN1JBE

HTTP status code 401

Bad, missing or expired token.

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
    "status": 401,
    "title": "Unauthorized",
    "detail": "Unauthorized"
}

/tenant

Management of tenant resources

get

get

This is the entry point for the administration of your tenant and can be used to manage the companies within the tenant.

/tenant/companies

Management of company resources, e.g. listing or creating companies

get post

get

Allows you to read all companies owned by the tenant.

post

Creates a company within the tenant.

Creates a company within the tenant.

Secured by Tenant Administration API Token

Body

Media type: application/vnd.mercateo-unite.administration.v1+json

Type: object

Properties

  • name : required (string)

    The official legal name of the organization.

  • vatId : (string)

    This is the value-added tax ID of the company. Must be a valid VatId according to http://ec.europa.eu/taxation_customs/vies/faqvies.do#item_11

  • noVatIdAvailable : (boolean)

    Value-added Tax ID field can only be empty in case this field is set to true

  • imprint : (string)

    The URL of the imprint of the company.

  • address : required (object)

    For any legal matters the company can be contacted with the given contact information.

    • street : required (string)

      Should contain street name and house number only.

    • additionalAddressInformation : (string)

      Additional address parts that are appended to the final address. In order to achieve the highest possible level of validation, flat numbers, building numbers, house number details like "A", names and similar parts should be passed into this request parameter.

    • locality : required (string)

      This is the city or village of the address.

    • postalCode : (string - maxLength: 10)

      This is the postal code of the address (e.g. ZIP in the US or PLZ in Germany).

    • countryCode : required (one of DE, FR, GB, NL, IT, AT, ES, IE, CZ, HU, PL, SK, CH, BE)

      This is the country where your company is located. We only allow creating companies in selected countries. The values are encoded as ISO_3166-1_alpha-2.

  • contact : required (object)

    For any legal matters the company can be contacted with the given contact information.

    • name : (string)

      The name of the contact person or department, which can be contacted.

    • email : required (string)

      The email address of the person or department, which can be contacted.

    • phone : (string)

      The telephone number of the person or department, which can be contacted.

{
  "name": "Mercateo AG",
  "vatId": "DE205372170",
  "noVatIdAvailable": false,
  "imprint": "http://imprint.url",
  "address": {
    "street": "Fürstenfelder Str. 5",
    "additionalAddressInformation": "Kaufingertor Passage",
    "locality": "München",
    "postalCode": "80331",
    "countryCode": "DE"
  },
  "contact": {
    "name": "Mercateo AG",
    "email": "service@mercateo.com",
    "phone": "+49(0)8912140777"
  }
}

HTTP status code 201

Returns a newly created company object

Body

Media type: application/vnd.mercateo-unite.administration.v1+json

Type: object

Properties

  • name : required (string)

    The official legal name of the organization.

  • vatId : (string)

    This is the value-added tax ID of the company. Must be a valid VatId according to http://ec.europa.eu/taxation_customs/vies/faqvies.do#item_11

  • imprint : (string)

    The URL of the imprint of the company.

  • address : required (object)

    For any legal matters the company can be contacted with the given contact information.

    • street : required (string)

      Should contain street name and house number only.

    • additionalAddressInformation : (string)

      Additional address parts that are appended to the final address. In order to achieve the highest possible level of validation, flat numbers, building numbers, house number details like "A", names and similar parts should be passed into this request parameter.

    • locality : required (string)

      This is the city or village of the address.

    • postalCode : (string - maxLength: 10)

      This is the postal code of the address (e.g. ZIP in the US or PLZ in Germany).

    • countryCode : required (one of DE, FR, GB, NL, IT, AT, ES, IE, CZ, HU, PL, SK, CH, BE)

      This is the country where your company is located. We only allow creating companies in selected countries. The values are encoded as ISO_3166-1_alpha-2.

  • contact : required (object)

    For any legal matters the company can be contacted with the given contact information.

    • name : (string)

      The name of the contact person or department, which can be contacted.

    • email : required (string)

      The email address of the person or department, which can be contacted.

    • phone : (string)

      The telephone number of the person or department, which can be contacted.

  • noVatIdAvailable : (boolean)

    Value-added Tax ID field can only be empty in case this field is set to true

  • companyId : required (string)

    Internal Id of the organization.

  • companyNumber : required (string)

    Internal Id of the organization.

  • _schema : required (object)
    • links : required (array of base.Link)

      Items: Link

      • href : required (string)
      • rel : required (string)
      • mediaType : (string)
      • method : (one of POST, GET, PUT, PATCH, DELETE, OPTIONS, HEAD)
      • relType : (string)
      • target : (string)
{
  "companyId": "88deaac5-27ac-482e-95b9-969b322f4684",
  "name": "Mercateo AG",
  "vatId": "DE205372170",
  "imprint": "http://imprint.url",
  "address": {
    "street": "Fürstenfelder Str. 5",
    "additionalAddressInformation": "Kaufingertor Passage",
    "locality": "München",
    "postalCode": "80331",
    "countryCode": "DE"
  },
  "contact": {
    "name": "Mercateo AG",
    "email": "service@mercateo.com",
    "phone": "+49(0)8912140777"
  },
  "companyNumber": "123456789",
  "_schema": {
    "links": [
      {
        "href": "https://administration.unite.services/api/tenant/companies/88deaac5-27ac-482e-95b9-969b322f4684",
        "method": "GET",
        "rel": "self"
      }
    ]
  }
}

HTTP status code 400

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 400,
  "title": "Invalid",
  "detail": "The request body is syntactically correct, but is not accepted, because of its data",
  "errors": [
    {
      "code": "ENUM",
      "path": "#/address/countryCode"
    },
    {
      "code": "INVALID_EMAIL",
      "path": "#/contact/email"
    },
    {
      "code": "INVALID_VAT_ID",
      "path": "#/vatId"
    },
    {
      "code": "MAXLENGTH",
      "path": "#/path/to/field",
      "limit": "maximum length as number"
    },
    {
      "code": "REQUIRED",
      "path": "#/path/to/field"
    }
  ]
}

HTTP status code 401

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
    "status": 401,
    "title": "Unauthorized",
    "detail": "Unauthorized"
}

HTTP status code 405

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 405,
  "title": "Method Not Allowed",
  "detail": "HTTP 405 Method Not Allowed"
}

HTTP status code 406

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 406,
  "title": "Not Acceptable",
  "detail": "Not Acceptable, doesn't include valid version, see valid versions here: https://portal.unite.eu/developers/apis/administration-api"
}

HTTP status code 415

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 415,
  "title": "Unsupported Media Type",
  "detail": "HTTP 415 Unsupported Media Type"
}

Secured by Tenant Administration API Token

Headers

  • Authorization : required (string)

    Endpoint expects an Authorization header containing a token for the Tenant Administration API using the Bearer schema.

    A token for the Tenant Administration API has its audience set to https://unite.eu/tenant-administration-api.

    Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL3VuaXRlLmV1L3RlbmFudF9pZCI6IjExMTExMTExLTExMTEtMTExMS0xMTExLTExMTExMTExMTExMSIsImh0dHBzOi8vdW5pdGUuZXUvY29tcGFueV9pZCI6IjIyMjIyMjIyLTIyMjItMjIyMi0yMjIyLTIyMjIyMjIyMjIyMiIsImh0dHBzOi8vdW5pdGUuZXUvZW1wbG95ZWVfaWQiOiIzMzMzMzMzMy0zMzMzLTMzMzMtMzMzMy0zMzMzMzMzMzMzMzMiLCJpc3MiOiJzZWxmLWlzc3VlZCIsInN1YiI6InN1YmplY3QiLCJhdWQiOiJodHRwczovL3VuaXRlLmV1L2FwaSIsInNjb3BlIjoib2ZmbGluZV9hY2Nlc3MifQ.VetLahLfqaRD5_sDEMgEYIxTyWmPUY-YuTlHLQN1JBE

HTTP status code 401

Bad, missing or expired token.

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
    "status": 401,
    "title": "Unauthorized",
    "detail": "Unauthorized"
}

/tenant/companies/{companyId}

Management of a specific company based on it's id

get

get

Allows you to get the information about a single company.

Allows you to get the information about a single company.

Secured by Tenant Administration API Token

URI Parameters

  • companyId : required (string - pattern: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})

    ID of the company

    88deaac5-27ac-482e-95b9-969b322f4684

HTTP status code 200

Returns all attributes of a company.

Body

Media type: application/vnd.mercateo-unite.administration.v1+json

Type: object

Properties

  • name : required (string)

    The official legal name of the organization.

  • vatId : (string)

    This is the value-added tax ID of the company. Must be a valid VatId according to http://ec.europa.eu/taxation_customs/vies/faqvies.do#item_11

  • imprint : (string)

    The URL of the imprint of the company.

  • address : required (object)

    For any legal matters the company can be contacted with the given contact information.

    • street : required (string)

      Should contain street name and house number only.

    • additionalAddressInformation : (string)

      Additional address parts that are appended to the final address. In order to achieve the highest possible level of validation, flat numbers, building numbers, house number details like "A", names and similar parts should be passed into this request parameter.

    • locality : required (string)

      This is the city or village of the address.

    • postalCode : (string - maxLength: 10)

      This is the postal code of the address (e.g. ZIP in the US or PLZ in Germany).

    • countryCode : required (one of DE, FR, GB, NL, IT, AT, ES, IE, CZ, HU, PL, SK, CH, BE)

      This is the country where your company is located. We only allow creating companies in selected countries. The values are encoded as ISO_3166-1_alpha-2.

  • contact : required (object)

    For any legal matters the company can be contacted with the given contact information.

    • name : (string)

      The name of the contact person or department, which can be contacted.

    • email : required (string)

      The email address of the person or department, which can be contacted.

    • phone : (string)

      The telephone number of the person or department, which can be contacted.

  • noVatIdAvailable : (boolean)

    Value-added Tax ID field can only be empty in case this field is set to true

  • companyId : required (string)

    Internal Id of the organization.

  • companyNumber : required (string)

    Internal Id of the organization.

  • _schema : required (object)
    • links : required (array of base.Link)

      Items: Link

      • href : required (string)
      • rel : required (string)
      • mediaType : (string)
      • method : (one of POST, GET, PUT, PATCH, DELETE, OPTIONS, HEAD)
      • relType : (string)
      • target : (string)
{
  "companyId": "88deaac5-27ac-482e-95b9-969b322f4684",
  "name": "Mercateo AG",
  "vatId": "DE205372170",
  "imprint": "http://imprint.url",
  "address": {
    "street": "Fürstenfelder Str. 5",
    "additionalAddressInformation": "Kaufingertor Passage",
    "locality": "München",
    "postalCode": "80331",
    "countryCode": "DE"
  },
  "contact": {
    "name": "Mercateo AG",
    "email": "service@mercateo.com",
    "phone": "+49(0)8912140777"
  },
  "companyNumber": "123456789",
  "_schema": {
    "links": [
      {
        "href": "https://administration.unite.services/api/tenant/companies/88deaac5-27ac-482e-95b9-969b322f4684",
        "method": "GET",
        "rel": "self"
      }
    ]
  }
}

HTTP status code 401

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
    "status": 401,
    "title": "Unauthorized",
    "detail": "Unauthorized"
}

HTTP status code 403

The company is not allowed to be accessed, because it is blocked.

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 403,
  "title": "Forbidden",
  "detail": "HTTP 403 Forbidden"
}

HTTP status code 404

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 404,
  "title": "Not Found",
  "detail": "Not Found"
}

HTTP status code 405

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 405,
  "title": "Method Not Allowed",
  "detail": "HTTP 405 Method Not Allowed"
}

HTTP status code 406

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
  "status": 406,
  "title": "Not Acceptable",
  "detail": "Not Acceptable, doesn't include valid version, see valid versions here: https://portal.unite.eu/developers/apis/administration-api"
}

Secured by Tenant Administration API Token

Headers

  • Authorization : required (string)

    Endpoint expects an Authorization header containing a token for the Tenant Administration API using the Bearer schema.

    A token for the Tenant Administration API has its audience set to https://unite.eu/tenant-administration-api.

    Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwczovL3VuaXRlLmV1L3RlbmFudF9pZCI6IjExMTExMTExLTExMTEtMTExMS0xMTExLTExMTExMTExMTExMSIsImh0dHBzOi8vdW5pdGUuZXUvY29tcGFueV9pZCI6IjIyMjIyMjIyLTIyMjItMjIyMi0yMjIyLTIyMjIyMjIyMjIyMiIsImh0dHBzOi8vdW5pdGUuZXUvZW1wbG95ZWVfaWQiOiIzMzMzMzMzMy0zMzMzLTMzMzMtMzMzMy0zMzMzMzMzMzMzMzMiLCJpc3MiOiJzZWxmLWlzc3VlZCIsInN1YiI6InN1YmplY3QiLCJhdWQiOiJodHRwczovL3VuaXRlLmV1L2FwaSIsInNjb3BlIjoib2ZmbGluZV9hY2Nlc3MifQ.VetLahLfqaRD5_sDEMgEYIxTyWmPUY-YuTlHLQN1JBE

HTTP status code 401

Bad, missing or expired token.

Body

Media type: application/problem+json

Type: object

Properties

  • type : (string)
  • status : required (integer)
  • title : required (string)
  • detail : (string)
  • errors : (union of object or array)
{
    "status": 401,
    "title": "Unauthorized",
    "detail": "Unauthorized"
}