💻 Purpose of the API

The NL Monitoring API allows you to track changes in the profiles of Dutch organizations and branches over time.

Instead of repeatedly polling the NL Organizations API to detect what changed, you can set up monitoring lists that automatically capture change events for the entities and data fields you care about.
You can use this API to:

Create named monitoring lists to group the entities you want to watch
Add items (organizations or branches) to a list, specifying which event types and data collections to track
Retrieve updates — change events generated by the system when monitored data fields are modified, created, or deleted
Manage lists and items (get, delete) for ongoing monitoring workflows

The API is ideal for compliance monitoring, regulatory change tracking, KYC/KYB continuous due diligence, portfolio surveillance, and any workflow that needs to react to changes in Dutch organization data.

🤔 How to use?

📌 Overview of the Flow

Create a Monitoring List
Start by calling
POST /nl/organizations/monitoring/v1/lists
to create a named container that will hold the entities you want to monitor.
Add Items to the List
Once you have a list_id, call:
POST /nl/organizations/monitoring/v1/lists/{list_id}/items
to add one or more organizations or branches. For each item you specify:
- The entity ID and type (organization or branch)
- The event type to watch (change)
- The collections (data fields) to monitor
Poll for Updates (List Level)
Periodically call:
GET /nl/organizations/monitoring/v1/lists/{list_id}/updates
with a date filter to retrieve all change events across every item in the list.
Poll for Updates (Item Level)
For a more targeted view, call:
GET /nl/organizations/monitoring/v1/items/{item_id}/updates
to get change events for a single monitored entity.
Manage Lists and Items
Use the GET and DELETE endpoints to inspect or clean up your monitoring configuration at any time.

🌀 Flow Behavior

If no updates occurred in the requested time range, the API returns an empty data: [] array — this is normal and not an error.
All list and item endpoints support pagination via page[number] and page[size].
Item responses include the parent list in the included section (JSON:API side-loading).
Update responses include the related organization in the included section with its Trade Register identifier and a link to the NL Organizations Profile API.
All responses follow JSON:API conventions for consistency.

🔢 Versioning

Current version prefix:
/nl/organizations/monitoring/v1/

Future versions will follow /v2/, /v3/, etc.

🌐 Base URL

https://api.company.info

🔑 Authentication

All requests must be authenticated using one of the following methods:

Method	Header	Description
API Key	`X-API-KEY: <your-api-key>`	Your unique API key. Validated against the Organization Management API.
Bearer Token	`Authorization: Bearer <your-token>`	A valid bearer token issued by the authentication service.

💡
You only need to provide one of these headers per request. If both are present, the bearer token takes precedence.

🧩 Core Concepts

Before diving into the endpoints it helps to understand the domain model:

Concept	Description
List	A named container that groups monitoring items together. Each customer can have up to 100 lists.
Item	A specific entity (organization or branch) to monitor within a list. Each item defines the entity, the event type to watch, and the collections to track.
Update	A change event generated by the system when a monitored collection on a watched entity is modified, created, or deleted. Updates are only visible for changes that occurred after the item was placed on a list.

📚 All Endpoints

Below is a complete list of API endpoints.

#	Method	Endpoint	Description
1	`POST`	`/v1/lists`	Create a new monitoring list
2	`GET`	`/v1/lists`	Get all lists for the customer
3	`GET`	`/v1/lists/{list_id}`	Get a specific list
4	`DELETE`	`/v1/lists/{list_id}`	Delete a list and all its items
5	`POST`	`/v1/lists/{list_id}/items`	Add items to a list
6	`GET`	`/v1/lists/{list_id}/items`	Get all items in a list
7	`GET`	`/v1/items/{item_id}`	Get a specific item
8	`DELETE`	`/v1/items/{item_id}`	Delete an item
9	`GET`	`/v1/lists/{list_id}/updates`	Get change updates for all items in a list
10	`GET`	`/v1/items/{item_id}/updates`	Get change updates for a specific item

All endpoint paths are relative to /nl/organizations/monitoring.

❗ These endpoints incur usage-based charges.

1. 📝 Create a List

POST /nl/organizations/monitoring/v1/lists

Create a new monitoring list.

Description

Creates a named container for organizing the entities you want to monitor. The list name must be alphanumeric (no special characters) and at most 50 characters long.

⁉️ Request Parameters

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.
`Content-Type`	string	Required. `application/json`

Request Body

Field	Type	Required	Description
`data.type`	string	Yes	Must be `"lists"`.
`data.attributes.name`	string	Yes	Name of the list. Alphanumeric, max 50 chars.

Example Request

curl -X POST "https://api.company.info/nl/organizations/monitoring/v1/lists" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "type": "lists",
          "attributes": {
            "name": "MyMonitoringList"
          }
        }
      }'

Example Response

{
  "data": {
    "id": "01HX6V58G64VJHWRDEJF0YKZ85",
    "type": "lists",
    "attributes": {
      "name": "MyMonitoringList",
      "createdAt": "2024-05-15T13:25:43+02:00"
    },
    "links": {
      "self": "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85"
    }
  }
}

Response Fields — `data`

Field	Type	Description
`id`	string	Unique identifier (ULID) for the list.
`type`	string	Always `"lists"`.
`attributes.name`	string	The name you provided.
`attributes.createdAt`	string	ISO 8601 timestamp of when the list was created.
`links.self`	string	Canonical URL to retrieve this list.

⚠️ Limitations

Maximum 100 lists per customer.
List name must be alphanumeric and at most 50 characters.

2. 📋 Get All Lists

GET /nl/organizations/monitoring/v1/lists

Retrieve all monitoring lists belonging to the authenticated customer.

Description

Returns a paginated array of all your monitoring lists.

⁉️ Request Parameters

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Query Parameters

Parameter	Type	Description
`page[number]`	integer	Page number (default: `1`).
`page[size]`	integer	Records per page (default: `10`, maximum: `20`).

Example Request

curl -X GET "https://api.company.info/nl/organizations/monitoring/v1/lists" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "01HX6V58G64VJHWRDEJF0YKZ85",
      "type": "lists",
      "attributes": {
        "name": "MyMonitoringList",
        "createdAt": "2024-05-15T13:25:43+02:00"
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85"
      }
    }
  ],
  "links": {
    "first": "...?page[number]=1&page[size]=10",
    "last": "...?page[number]=1&page[size]=10",
    "self": "...?page[number]=1&page[size]=10"
  },
  "meta": {
    "totalResults": 1,
    "totalPages": 1
  }
}

3. 📄 Get a Single List

GET /nl/organizations/monitoring/v1/lists/{list_id}

Retrieve a single monitoring list by its ID.

Description

Returns the details of the specified list.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`list_id`	string	Yes	The ID of the list.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Example Request

curl -X GET "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "01HX6V58G64VJHWRDEJF0YKZ85",
    "type": "lists",
    "attributes": {
      "name": "MyMonitoringList",
      "createdAt": "2024-05-15T13:25:43+02:00"
    },
    "links": {
      "self": "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85"
    }
  }
}

4. 🗑️ Delete a List

DELETE /nl/organizations/monitoring/v1/lists/{list_id}

Delete a monitoring list and all items associated with it.

Description

Permanently removes the specified list. All items within the list are also deleted. This action cannot be undone.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`list_id`	string	Yes	The ID of the list.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Example Request

curl -X DELETE "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

204 No Content — the list and all its items have been deleted.

5. ➕ Add Items to a List

POST /nl/organizations/monitoring/v1/lists/{list_id}/items

Add one or more monitoring items (organizations or branches) to a list.

Description

Items define what to watch, which event type to listen for, and which collections (data fields) to track. You can add multiple items in a single request.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`list_id`	string	Yes	The ID of the list to add items to.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.
`Content-Type`	string	Required. `application/json`

Request Body

The body must contain a data array. Each element requires:

Field	Type	Required	Description
`type`	string	Yes	Must be `"items"`.
`attributes.entity.id`	string	Yes	Trade Register ID — 8-digit KVK number (organization) or 12-digit branch number.
`attributes.entity.type`	string	Yes	`"organization"` or `"branch"`.
`attributes.eventType`	string	Yes	Event type to watch: `"change"`.
`attributes.collections`	string[]	Yes	Array of collection names to monitor (see Supported Collections below).

Example Request

curl -X POST "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85/items" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "data": [
          {
            "type": "items",
            "attributes": {
              "entity": {
                "id": "33302047",
                "type": "organization"
              },
              "eventType": "change",
              "collections": ["name", "activities", "address"]
            }
          },
          {
            "type": "items",
            "attributes": {
              "entity": {
                "id": "000012345678",
                "type": "branch"
              },
              "eventType": "change",
              "collections": ["name", "contact"]
            }
          }
        ]
      }'

Example Response

{
  "data": [
    {
      "id": "01HX71K7DSM0JA59XJZ07MQG2W",
      "type": "items",
      "attributes": {
        "entity": {
          "id": "33302047",
          "type": "organization"
        },
        "eventType": "change",
        "collections": ["name", "activities", "address"],
        "createdAt": "2024-05-15T13:30:12+02:00"
      },
      "relationships": {
        "list": {
          "data": {
            "type": "lists",
            "id": "01HX6V58G64VJHWRDEJF0YKZ85"
          }
        }
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/monitoring/v1/items/01HX71K7DSM0JA59XJZ07MQG2W"
      }
    },
    {
      "id": "01HX71K7DSM0JA59XJZ07MQG2X",
      "type": "items",
      "attributes": {
        "entity": {
          "id": "000012345678",
          "type": "branch"
        },
        "eventType": "change",
        "collections": ["name", "contact"],
        "createdAt": "2024-05-15T13:30:12+02:00"
      },
      "relationships": {
        "list": {
          "data": {
            "type": "lists",
            "id": "01HX6V58G64VJHWRDEJF0YKZ85"
          }
        }
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/monitoring/v1/items/01HX71K7DSM0JA59XJZ07MQG2X"
      }
    }
  ],
  "included": [
    {
      "id": "01HX6V58G64VJHWRDEJF0YKZ85",
      "type": "lists",
      "attributes": {
        "name": "MyMonitoringList",
        "createdAt": "2024-05-15T13:25:43+02:00"
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85"
      }
    }
  ]
}

Response Fields — `data[]`

Field	Type	Description
`id`	string	Unique identifier (ULID) for the item.
`type`	string	Always `"items"`.
`attributes.entity.id`	string	The entity's Trade Register ID.
`attributes.entity.type`	string	`"organization"` or `"branch"`.
`attributes.eventType`	string	The event type being monitored.
`attributes.collections`	string[]	The list of collections being monitored.
`attributes.createdAt`	string	ISO 8601 timestamp of when the item was created.
`relationships.list.data.type`	string	Always `"lists"`.
`relationships.list.data.id`	string	The ID of the parent list.
`links.self`	string	Canonical URL to retrieve this item.

Response Fields — `included[]`

The parent list is side-loaded in the included array following JSON:API conventions.

⚠️ Limitations

Maximum 1000 items per single request.
Entity ID must be an 8-digit number (organization) or 12-digit number (branch).
Collections must be valid for the entity type (see Supported Collections below).

6. 📋 Get All Items in a List

GET /nl/organizations/monitoring/v1/lists/{list_id}/items

Retrieve all monitoring items belonging to a specific list.

Description

Returns a paginated array of all items in the specified list, with the parent list side-loaded in included.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`list_id`	string	Yes	The ID of the list.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Query Parameters

Parameter	Type	Description
`page[number]`	integer	Page number (default: `1`).
`page[size]`	integer	Records per page (default: `10`, maximum: `20`).

Example Request

curl -X GET "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85/items" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "01HX71K7DSM0JA59XJZ07MQG2W",
      "type": "items",
      "attributes": {
        "entity": {
          "id": "33302047",
          "type": "organization"
        },
        "eventType": "change",
        "collections": ["name", "activities", "address"],
        "createdAt": "2024-05-15T13:30:12+02:00"
      },
      "relationships": {
        "list": {
          "data": {
            "type": "lists",
            "id": "01HX6V58G64VJHWRDEJF0YKZ85"
          }
        }
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/monitoring/v1/items/01HX71K7DSM0JA59XJZ07MQG2W"
      }
    }
  ],
  "included": [
    {
      "id": "01HX6V58G64VJHWRDEJF0YKZ85",
      "type": "lists",
      "attributes": {
        "name": "MyMonitoringList",
        "createdAt": "2024-05-15T13:25:43+02:00"
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85"
      }
    }
  ],
  "links": {
    "first": "...?page[number]=1&page[size]=10",
    "last": "...?page[number]=1&page[size]=10",
    "self": "...?page[number]=1&page[size]=10"
  },
  "meta": {
    "totalResults": 1,
    "totalPages": 1
  }
}

7. 📄 Get a Single Item

GET /nl/organizations/monitoring/v1/items/{item_id}

Retrieve a single monitoring item by its ID.

Description

Returns the full details of the specified item, including its parent list in the included section.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`item_id`	string	Yes	The ID of the item.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Example Request

curl -X GET "https://api.company.info/nl/organizations/monitoring/v1/items/01HX71K7DSM0JA59XJZ07MQG2W" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "01HX71K7DSM0JA59XJZ07MQG2W",
    "type": "items",
    "attributes": {
      "entity": {
        "id": "33302047",
        "type": "organization"
      },
      "eventType": "change",
      "collections": ["name", "activities", "address"],
      "createdAt": "2024-05-15T13:30:12+02:00"
    },
    "relationships": {
      "list": {
        "data": {
          "type": "lists",
          "id": "01HX6V58G64VJHWRDEJF0YKZ85"
        }
      }
    },
    "links": {
      "self": "https://api.company.info/nl/organizations/monitoring/v1/items/01HX71K7DSM0JA59XJZ07MQG2W"
    }
  },
  "included": [
    {
      "id": "01HX6V58G64VJHWRDEJF0YKZ85",
      "type": "lists",
      "attributes": {
        "name": "MyMonitoringList",
        "createdAt": "2024-05-15T13:25:43+02:00"
      },
      "links": {
        "self": "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85"
      }
    }
  ]
}

8. 🗑️ Delete an Item

DELETE /nl/organizations/monitoring/v1/items/{item_id}

Remove a single monitoring item.

Description

Permanently removes the specified item from its list. The entity will no longer be monitored. This action cannot be undone.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`item_id`	string	Yes	The ID of the item.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Example Request

curl -X DELETE "https://api.company.info/nl/organizations/monitoring/v1/items/01HX71K7DSM0JA59XJZ07MQG2W" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

204 No Content — the item has been deleted.

9. 🔔 Get Updates for a List

GET /nl/organizations/monitoring/v1/lists/{list_id}/updates

Retrieve change events for all items in a list.

Description

Returns a paginated array of updates (change events) that occurred on any monitored entity within the specified list during the given time range. Updates include the entity that changed, the event type, the collection that was modified, and when the change was published.

⚠️
Updates are only visible for changes that occurred after the
item was placed on a list. Historical changes before the item was added will not appear.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`list_id`	string	Yes	The ID of the list.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Query Parameters

Parameter	Type	Required	Description
`filter[date][from]`	string	Yes	Start of the update window (RFC 3339 format). Cannot be in the future.
`filter[date][to]`	string	No	End of the update window (RFC 3339). Must be after `from` and not in the future.
`filter[eventType]`	string	No	Filter by event type: `change`.
`filter[entity][id]`	string	No	Filter by a specific entity ID (8-digit or 12-digit).
`filter[collections]`	string	No	Comma-separated list of collection names to filter by.
`page[number]`	integer	No	Page number (default: `1`).
`page[size]`	integer	No	Records per page (default: `100`, maximum: `200`).

Example Request

curl -X GET "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85/updates?filter[date][from]=2024-05-15T00:00:00Z&filter[eventType]=change" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "01HQ8DJJAZW067WSTRM6M7EWB2",
      "type": "updates",
      "attributes": {
        "entity": {
          "id": "33302047",
          "type": "organization"
        },
        "eventType": "change",
        "collection": "name",
        "publishedAt": "2024-05-16T09:12:33+02:00"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "33302047"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "organizations",
      "id": "33302047",
      "attributes": {
        "identifiers": {
          "tradeRegister": {
            "system": "tradeRegister",
            "value": "33302047"
          }
        }
      },
      "links": {
        "self": "https://api.company.info/v1/organizations/33302047"
      }
    }
  ],
  "links": {
    "first": "...?page[number]=1&page[size]=100",
    "last": "...?page[number]=1&page[size]=100",
    "self": "...?page[number]=1&page[size]=100"
  },
  "meta": {
    "totalResults": 1,
    "totalPages": 1
  }
}

Response Fields — `data[]`

Field	Type	Description
`id`	string	Unique identifier for the update event.
`type`	string	Always `"updates"`.
`attributes.entity.id`	string	The Trade Register ID of the entity that changed.
`attributes.entity.type`	string	`"organization"` or `"branch"`.
`attributes.eventType`	string	The type of event (`"change"`).
`attributes.collection`	string	The specific collection that was modified.
`attributes.publishedAt`	string	ISO 8601 timestamp of when the change was published.
`relationships.organization.data.type`	string	Always `"organizations"`.
`relationships.organization.data.id`	string	The organization ID related to this update.

Response Fields — `included[]`

The related organization is side-loaded with its Trade Register identifier and a self-link pointing to the NL Organizations Profile API.

⚠️ Constraints

The filter[date][from] parameter is required.
The maximum time range between from and to is 1 year (8766 hours).
The from date cannot be in the future.
The to date must be after the from date and cannot be in the future.

10. 🔔 Get Updates for an Item

GET /nl/organizations/monitoring/v1/items/{item_id}/updates

Retrieve change events for a single monitored item.

Description

Same as list-level updates, but scoped to a single item. Useful when you want to inspect changes for one specific entity without retrieving the full list.

⚠️
Updates are only visible for changes that occurred after the
item was placed on a list. Historical changes before the item was added will not appear.

⁉️ Request Parameters

Path

Name	Type	Required	Description
`item_id`	string	Yes	The ID of the item.

Headers

Name	Type	Description
`X-API-KEY`	string	Your API key. Required if `Authorization` is not provided.
`Authorization`	string	Bearer token (`Bearer <token>`). Required if `X-API-KEY` is not provided.

Query Parameters

Parameter	Type	Required	Description
`filter[date][from]`	string	Yes	Start of the update window (RFC 3339 format). Cannot be in the future.
`filter[date][to]`	string	No	End of the update window (RFC 3339). Must be after `from` and not in the future.
`filter[eventType]`	string	No	Filter by event type: `change`.
`filter[entity][id]`	string	No	Filter by a specific entity ID.
`filter[collections]`	string	No	Comma-separated list of collection names to filter by.
`page[number]`	integer	No	Page number (default: `1`).
`page[size]`	integer	No	Records per page (default: `100`, maximum: `200`).

Example Request

curl -X GET "https://api.company.info/nl/organizations/monitoring/v1/items/01HX71K7DSM0JA59XJZ07MQG2W/updates?filter[date][from]=2024-05-15T00:00:00Z" \
  -H "X-API-KEY: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "01HQ8DJJAZW067WSTRM6M7EWB3",
      "type": "updates",
      "attributes": {
        "entity": {
          "id": "33302047",
          "type": "organization"
        },
        "eventType": "change",
        "collection": "activities",
        "publishedAt": "2024-05-16T14:45:00+02:00"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "33302047"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "organizations",
      "id": "33302047",
      "attributes": {
        "identifiers": {
          "tradeRegister": {
            "system": "tradeRegister",
            "value": "33302047"
          }
        }
      },
      "links": {
        "self": "https://api.company.info/v1/organizations/33302047"
      }
    }
  ],
  "links": {
    "first": "...?page[number]=1&page[size]=100",
    "last": "...?page[number]=1&page[size]=100",
    "self": "...?page[number]=1&page[size]=100"
  },
  "meta": {
    "totalResults": 1,
    "totalPages": 1
  }
}

⚠️ Constraints

The filter[date][from] parameter is required.
The maximum time range between from and to is 1 year (8766 hours).
The from date cannot be in the future.
The to date must be after the from date and cannot be in the future.

📦 Supported Collections

Collections define which data fields of an entity you want to monitor for changes. The available collections depend on the entity type.

Organization Collections

Collection	Description
`activities`	Business activities (SBI codes)
`address`	Visiting address
`authorized-capital`	Authorized capital
`contact`	Contact details
`contributed-capital`	Contributed capital
`correspondence-address`	Correspondence address
`dissolution-and-liquidation`	Dissolution and liquidation events
`insolvency-publications`	Insolvency publication records
`insolvency-status`	Insolvency status
`issued-capital`	Issued capital
`legal-form`	Legal form
`lifecycle`	Lifecycle status
`main-branch`	Main branch data
`main-branch--activities`	Main branch activities
`main-branch--address`	Main branch address
`main-branch--contact`	Main branch contact
`main-branch--correspondence-address`	Main branch correspondence address
`main-branch--lifecycle`	Main branch lifecycle
`main-branch--name`	Main branch name
`main-branch--personnel`	Main branch number of employees
`main-branch--trade-names`	Main branch trade names
`name`	Organization name
`rsin`	RSIN number
`statutory-seat`	Statutory seat
`extension--activities--company-info`	Extended activities data (Company.info source)
`extension--activities--trade-register`	Extended activities data (Trade Register source)
`extension--activity-summary`	Activity description summary
`extension--contact-person`	Contact person data
`extension--financials`	Financial data
`extension--management`	Management data
`extension--number-of-branches`	Number of branches
`extension--ownership-structure`	Ownership structure
`extension--size-indicators`	Size indicators
`internal--combined-name-change`	Combined name change tracking
`internal--dissolution-and-liquidation`	Internal dissolution and liquidation tracking

Branch Collections

Collection	Description
`activities`	Business activities (SBI codes)
`address`	Visiting address
`branch-transfer`	Branch transfer data
`contact`	Contact details
`correspondence-address`	Correspondence address
`lifecycle`	Lifecycle status
`main-branch`	Main branch data
`name`	Branch name
`personnel`	Number of employees
`trade-names`	Trade names
`extension--transfers`	Transfer data

🔢 Pagination

The API uses JSON:API-style pagination with meta and links objects.

Request Parameters

Parameter	Type	Description
`page[number]`	integer	The page number you want to retrieve (1-based, default: `1`).
`page[size]`	integer	How many records per page.

Default and maximum values differ by resource type:

Resource	Default `page[size]`	Maximum `page[size]`
Lists & Items	10	20
Updates	100	200

Response Fields

"meta": {
  "totalResults": 50,
  "totalPages": 5
},
"links": {
  "first": "...?page[number]=1&page[size]=10",
  "last": "...?page[number]=5&page[size]=10",
  "self": "...?page[number]=2&page[size]=10",
  "next": "...?page[number]=3&page[size]=10",
  "prev": "...?page[number]=1&page[size]=10"
}

Use links.next until it no longer appears or until you have all records.
Use totalResults and totalPages to build progress indicators or pagination controls in your UI.

🔄 Typical Polling Workflow

Here is a recommended workflow for continuously monitoring changes:

Create a list (Endpoint 1) — do this once.
Add items (Endpoint 5) — add the organizations/branches you want to watch, specifying collections and event type.
Poll for updates (Endpoint 9) — periodically call the list updates endpoint with filter[date][from] set to your last poll time.
Process updates — for each update, use the entity.id and collection fields to determine what changed, then fetch the latest data from the NL Organizations Profile API.
Repeat — adjust filter[date][from] to the timestamp of your last successful poll.

Example Polling Call (Daily)

curl -X GET "https://api.company.info/nl/organizations/monitoring/v1/lists/01HX6V58G64VJHWRDEJF0YKZ85/updates?filter[date][from]=2024-05-15T00:00:00Z&filter[date][to]=2024-05-16T00:00:00Z&page[size]=200" \
  -H "X-API-KEY: YOUR_API_KEY"

⚠️ Rate Limiting / Other Limitations

Constraint	Limit
Lists per customer	100
Items per single POST request	1000
List name length	50 characters (alphanumeric)
Update date range	Maximum 1 year (8766 hours)
Entity ID (organization)	8-digit number
Entity ID (branch)	12-digit number

❗️
Some environments may enforce additional rate limits per API key.

⚠️ Possible errors / unexpected behavior

Below is a table with the most common HTTP error responses.

Status	Error	Description	How to solve
400	Bad Request	Validation error (invalid entity ID, collection, date range, exceeded limits)	Validate parameter names and formats. Check that entity IDs are 8 or 12 digits and collections are valid for the entity type.
401	Unauthorized	Missing or invalid credentials	Ensure `X-API-KEY` or `Authorization: Bearer <token>` is present, not expired, and has sufficient permissions.
403	Forbidden	Insufficient permissions for the operation	Check that your API key is authorized for the Monitoring API.
404	Not Found	List or item not found	Confirm the `list_id` / `item_id` exists and belongs to your customer account.
500	Internal Server Error	Unexpected server error	Retry the request after some time. If it persists, contact support with `X-Correlation-Id`.

Example Error Response

{
  "errors": [
    {
      "status": "400",
      "code": "validation",
      "title": "Bad Request",
      "detail": "invalid entity ID"
    }
  ]
}

🛠️ Try it yourself!

✅
Ready to try it out? Head over to our API reference where you can easily test the API yourself.

From there, you can:

Explore endpoints
Play with example requests and responses
See schemas and parameter details
Use your own API key to test real responses

🔤 Glossary

Term	Definition
List	A named container grouping monitoring items together. Each customer can have up to 100 lists.
Item	A specific entity (organization or branch) being monitored within a list, along with its event type and collections.
Update	A change event generated when a monitored collection on a watched entity is modified. Only visible for changes after the item was placed on a list.
Collection	A category of data fields on an entity (e.g., `name`, `activities`, `address`). Collections define what is being tracked.
Event Type	The kind of change being monitored: `change` (data modification).
Trade Register ID	Official identifier issued by the Dutch Chamber of Commerce (KvK). 8 digits for organizations, 12 digits for branches.
ULID	Universally Unique Lexicographically Sortable Identifier — used for list and item IDs.
JSON:API	A specification for building APIs in JSON with consistent structure for `data`, `included`, `meta`, `links`, and `errors`.
Polling	The practice of periodically calling the updates endpoint to check for new changes.
Side-loading	JSON:API convention of including related resources in the `included` array to reduce the need for additional requests.
RFC 3339	A date/time format standard (e.g., `2024-05-15T00:00:00Z`) used for all date parameters in this API.

💻 Purpose of the API

🤔 How to use?

📌 Overview of the Flow

🌀 Flow Behavior

🔢 Versioning

🌐 Base URL

🔑 Authentication

You only need to provide one of these headers per request. If both are present, the bearer token takes precedence.

🧩 Core Concepts

📚 All Endpoints

1. 📝 Create a List

Description

⁉️ Request Parameters

Headers

Request Body

Example Request

Example Response

Response Fields — data

⚠️ Limitations

2. 📋 Get All Lists

Description

⁉️ Request Parameters

Headers

Query Parameters

Example Request

Example Response

3. 📄 Get a Single List

Description

⁉️ Request Parameters

Path

Headers

Example Request

Example Response

4. 🗑️ Delete a List

Description

⁉️ Request Parameters

Path

Headers

Example Request

Example Response

5. ➕ Add Items to a List

Description

⁉️ Request Parameters

Path

Headers

Request Body

Example Request

Example Response

Response Fields — data[]

Response Fields — included[]

⚠️ Limitations

6. 📋 Get All Items in a List

Description

⁉️ Request Parameters

Path

Headers

Query Parameters

Example Request

Example Response

7. 📄 Get a Single Item

Description

⁉️ Request Parameters

Path

Headers

Example Request

Example Response

8. 🗑️ Delete an Item

Description

⁉️ Request Parameters

Path

Headers

Example Request

Example Response

9. 🔔 Get Updates for a List

Description

Updates are only visible for changes that occurred after the

⁉️ Request Parameters

Path

Headers

Query Parameters

Response Fields — `data`

Response Fields — `data[]`

Response Fields — `included[]`

Response Fields — `data[]`

Response Fields — `included[]`