Using the Changes endpoint

All changes to companies (eg. new accounting figures, changed phone numbers, change in roles or shareholdes) are tracked in the Changes endpoint.

Often you may want to receive updates to a company in your system only when the details of the company has changed. The easiest way to accomplish this is to store the fields you are interested (say, name, phoneNumber and address). Then lookup the company by organization number using /api/companies/register/{country}/{id} and compare the corresponding field values. You can schedule this lookup on e.g. a weekly or daily basis. This works well if you have a relatively small amount of companies you update (e.g. less than 5000), but if you have a lot more this process does not scale well. In this case you can use the changes endpoint to check if there has been any changes to the companies you are interested in.

Background

To understand how the changes endpoint (/api/changes/register/) work, a little background on how we manage the data in our systems is useful. We are collecting company information from several sources and combining it into one document. This document is indexed and made searchable. This document is what the Proff API returns, and is what you see on Proff.no. This process is complex and time consuming and usually run once pr. day. On some occasions it may run more than once pr. day.

Step 1: Indexing

After this indexing process has run, we run another process that collects all the changes between the new version of the document and the old. This results in a new document, referred to as ChangedEntity. This document includes the company id (organization number) that was changed, when the ChangedEntity was created and a patchId that uniquely identifies this changed doc.

Step 2: Changes

Basic changes request

The most basic request to the changes endpoint looks like this (using curl):

curl \
> -H 'api-version: 1.1' \
> -H 'Authorization: Token <YOUR API TOKEN>' \
> https://api.proff.no/api/changes/register/NO

By default this will return all companies that are newly established, that have been removed or that have changed properties, within the last day. See the detailed API documentation (opens new window) for more details of possible parameters.

Scrolling

There may be more than 10 000 changed entities the last day (or more if you look back further using the since parameter). Pagination is not supported beyond 10 000 documents, therefore the changes endpoint offers an alternative approach to pagination referred to as scrolling.

The changes endpoint returns up to 1000 results in one request. If there are more than 1000 results (examine the numberOfHits property) you can fetch the next batch of results using the href of the link object with the relation attribute next (see the example below):

{
  "numberOfHits": 68365,
  "changedDocs": [
    {
      "id": "810059672",
      "patch": null,
      "createdDate": 1623565471312,
      "patchId": "26c6c1accb988e4bae243594a1dd6dd001434bacc6746d28e7a858f3b59008ea"
    },
  // More documents ...
  ],
  link: {
    "href": "https://api.proff.no/changes/register/NO?scrollId=DnF1ZXJ5VGhlbkZldGNoAwAAAAAbe5vMFkpweklhMTV2UUlhbU82VEhlaHJ0QncAAAAAG",
    "rel": "next"    
  } 
}

When changedDocs is an empty array there are no more results to retrieve and you can stop fetching new results.