Upload companies using your internal IDs

How does Avallone identify companies by default?

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.

Example

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 your own Company Identifiers?

However, there is a benefit in using status identifiers i.e. they remain the same across requests - they never change for the company. Reasons are:

Company Lookup

You can lookup the companies using your identifiers WIP

Incremental Updates

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

Configuration

If you want to make sure that Avallone uses the identifiers coming from your side, you can configure the sync process by explicitly specifying the company id fields:

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"
    }
  ]
}