📦 JSON API

All Company.info APIs follow the JSON:API specification — a standardized format for structuring requests and responses in JSON.

This ensures consistency across all APIs in the Hub, making integration more predictable, maintainable, and efficient for developers.

Structure of JSON API

Company.info APIs adhere to the JSON:API specification, which defines a consistent structure for both requests and responses. Below are the key components of the format:

Resource Objects
• Represent core entities in the API.
• Each resource includes a type and an id.
• The attributes object contains data fields for the resource.
• The relationships object defines links to related resources.

Document Structure
• Every response is a JSON object containing one or more of the following top-level keys:
• data: the primary resource(s) returned.
• errors: contains error information when a request fails.
• meta: includes additional metadata, such as pagination.
• included: used to sideload related resources.

Relationships
• Relationships between resources are represented in a dedicated relationships object.
• To fetch related resources in the same response, use the include query parameter (e.g. ?include=parent,children).

Included Resources
• The included section (optional) returns related resources that are part of the relationships defined in data.
• This avoids additional API calls and improves performance.

Error Handling
• All errors are returned in a standardized structure under the errors key.
• Each error object may include:
• code: application-specific error code
• title: brief summary of the error
• detail: human-readable explanation of what went wrong

Meta Information
• The meta object provides non-standard, supplementary information.
• It can appear alongside data, errors, or on its own—for example, to describe pagination or versioning.

Example Responses

✅ Successful response:

{
  // the main resource object
  "data": [
    {
      "id": "0123456",
      "type": "orders",
      // attributes contains the actual requested data 
      "attributes": {
        "companyName": "Company A",
        "correspondenceAddress": {
          "city": "Amsterdam",
          "street": "amsterdamstraat"
        },
      },
      // (optional) links an object to another object if there is an relationship between them
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "1234567"
          }
        }
      },
      // links contains the link to the object itself or other related objects
      "links": {
        "self": "https://example.com/0123456"
      }
    }
  ],
  // (optional) includes the object that is linked with the relationship object 
  "included": [
    {
      "type": "organizations",
      "id": "1234567",
      "attributes": {
        "tradeRegisterID": "98765"
      },
      "links": {
        "self": "https://example.com/1234567"
      }
    }
  ],
  // (optional) links contains the link to the object itself or other related objects
  "links": {
    "first": "https://example.com/",
    "last": "https://example.com/",
    "next": "https://example.com/",
    "prev": "https://example.com/",
    "self": "https://example.com/"
  },
  // (optional) additional information that is not linked to the object, but is useful
  "meta": {
    "totalResults": 0,
    "totalPages": 0
  }
}

❌ Error response:

{
  "errors": [
    {
      "title": "failed to fetch requested order",
      "detail": "the parameter 'address' is a required field",
      "status": "400",
      "code": "400"
    }
  ]
}