Upload companies using static IDs

How does Avallone uniquely identify companies?

By default, Avallone uses the combination of registrationNumber and name to uniquely identify the companies. If a company exists, the sync process will update the company, otherwise a new one will be created. This has the following benefits:

Import data from multiple sources

Data can be imported from multiple sources e.g. public registers as well as private/internal systems (CRM, MDM, etc)

Better Developer experience

The referenceId used to lookup the connections between companies doesn’t have to remain the same for all the requests. This makes it easy to test the API and use random reference ids as long as they are used consistently within the payload.

Consider the following:

{
  "companies": [
    {
      "referenceId": "a",
      "name": "Acme Inc",
      "registrationNumber": "acme-inc"
    },
    {
      "referenceId": "b",
      "name": "Wayne Corp",
      "registrationNumber": "wayne-corp",
      "parentCompanies": [
        {
          "referenceId": "a", <----- This doesn't have to be the same for all requests
          "ownership": 25
        }
      ]
    }
  ]
}

The referenceId for company Acme Inc is a for this particular request. It is used by company Wayne Corp to find the parent company. Avallone only uses it to do a lookup at the time of data import but uses registrationNumber and name to uniquely identify companies. This means that the referenceId can change across requests.

Why use static IDs?

Using Static IDs means that they they remain the same across requests. Or simply, they never change. You should consider using them for following reasons:

Company Lookup

You can lookup the companies using IDs you know e.g. if they are coming from your internal systems. WIP

Incremental Updates

You can make incremental updates e.g. create a relation between 2 companies without having to provide any additional context.

How to configure the sync process to use static IDs?

You can explicitly specifying the config.companyIdFields to ["referenceId"] as shown below:

PUT :url/api/v1/sync
Authorization: Bearer :token
Content-Type: application/json
{
  "config": {
    "companyIdFields": ["referenceId"],
  },
  "companies": [
    {
      "referenceId": "95f03f73-c9b7-11ed-8045-5615dd1da186",
      "name": "Acme Inc",
      "registrationNumber": "acme-inc"
    }
  ]
}