Smart merging of record when creating or updating

Connec! API offers the possibility to automatically match an existing record when pushing data. A list of fields to match against any existing records can be specified.

Use cases

Applications part of the Maestrano ecosystem have their own validations and constraints. Some may enforce entities to have unique values. A common scenario is to have a unique Product SKU, Customer reference or Invoice number.

Data creation

When your application sends a record to Connec! for the first time, you may want to merge it with any existing data that would come from another application. Failing to do so will create a duplicate that will then be pushed to other applications.

Importing data into your application

The first time a user links your application to its ecosystem, you may need to import data to populate the user's account. In the case this user was already using your application and data exists, it should be merged to avoid creating duplicates. This can be done in two different ways:

Option 1: Data is imported into your application and you must define rules to match incoming records with existing data within your application. Recommended if you store the ID mapping within your system

Option 2: Before importing Connec! data, you push the data from your application to Connec! specifying the records merging rules. Recommended if you rely on Connec! to store your application internal IDs

(see Working with records external IDs for ID mapping management)

Specify matching fields

When creating an entity, you can specify which attributes you want to use to merge with an existing record. If a record is matched, it will behave like an update request and return the existing entity with a 200 status code. This can be specified with the option matching_fields

Match on a single field

For example, if you push an Item to Connec! and within your application, Items are unique by SKU, you can specify to merge with any existing record having the same SKU:

POST /api/v2/cld-abcd/items
{
  "items": {
    "opts": {"matching_fields": ['reference']},
    "name": "Hammer 240g",
    "reference": "HM28731"
  }
}

With a matching item found

HTTP 200
{
  "items": {
    "name": "Hammer 240g",
    "reference": "HM28731",
    "description" : "Lightweight hammer"
  }
}

Match on several fields

You can also match on a combination of fields (matches by name and reference)

POST /api/v2/cld-abcd/items
{
  "items": {
    "opts": {"matching_fields": ['name', 'reference']},
    "name": "Hammer 240g",
    "reference": "HM28731"
  }
}

Specify several matching criteria

Or match on multiple sets of fields (matches either by name or reference)

POST /api/v2/cld-abcd/items
{
  "items": {
    "opts": {"matching_fields": [['name'], ['reference']]},
    "name": "Hammer 240g",
    "reference": "HM28731"
  }
}

Combined with ID mapping management

You can specify both the ID of your application and merging rules. This way Connec! will take care of matching records and storing your application ID so you do not have to maintain a mapping between your application records and Connec! records.

POST /api/v2/cld-abcd/items

Headers
  CONNEC-EXTERNAL-IDS: true
Body

{
  "items": {
    "opts": {"matching_fields": ['reference']},
    "id": [        {
      "realm": "unique-account-id",
      "provider": "my-app",
      "id": "92834"
    }
    "name": "Hammer 240g",
    "reference": "HM28731"
  }
}

Recommended matching options

Accounts

• name, class, type, sub_type (if your application manages accounts classification)
• name (if your application does not manage accounts details such as a CRM)

Organizations

• reference
• name (if your application enforces unique names)

People

• first_name, last_name, organization_id

Items

• reference

Transactions (Invoices, Payments, PurchaseOrders, etc...)

• transaction_number

Tax Codes

• tax_type
• name, sale_tax_rate, purchase_tax_rate