Record Matching Overview

Determining how a record in the import request is handled: (Create a new Kindful record vs. Update an existing Kindful record vs. Ignore)

Updating records and preventing duplicates

When using our /imports API, you need to specify if and how the API matches your request records with existing records in the Kindful database.

Your specification for "match_by" when creating a new record in Kindful will influence how you will be able to update those records later.

We recommend using the default "match_by" of "external_id". The ID you use can be the Unique ID you use in your system to identify the contact. To do so, pass a unique ID in requests for all records you create via the Kindful API so that you can subsequently update records via that ID.

Sample Create Request with Unique ID

                COPY
              
{
  "data_format": "contact",
  "data_type": "json",
  "action_type": "create",
  "data": [
    {
      "id": "123", // This is your unique ID
      "first_name": "Pete",
      "last_name": "Brumm"
    }
  ]
}

See more sample requests in the Kindful Customer API Reference

Example Usage

Let's say you send the following API request to Kindful to create a new contact:

                COPY
              
{
  "data_format": "contact",
  "action_type": "create",
  "match_by": {
    "contact": "external_id"  // This is the default. see "Record Matching options section"
  },
  "data": [
    {
      "id": "123",
      "first_name": "Pete",
      "last_name": "Brumm",
      "transaction_id": "467",
      "campaign": "General",
      "amount_in_cents": "200",
      "transaction_time": "2015-10-13 18:56:12 UTC",
      "transaction_updated_at": "2015-10-13 18:56:12 UTC"
    }
  ]
}

Kindful will use the "id": "123" to match against our integration table for your application as the external_id. If this record exists, then Kindful already has a record of this contact and will not create it again.

This enables the developer to send the same contact multiple times and not create duplicates. The developer also does not need to maintain the matching between their database ID's and Kindfuls.

Another Example

Below is an example of what is added to Kindful when specifying a "create" contact with id=“1”, where id is considered the "external_id" in Kindful (the ID of your third party system):

id	first_name	last_name
YOUR REQUEST
1 `// your external_id`	Pete	B

This record would be inserted and assigned a Kindful ID. (Let's say 5000).

id	first_name	last_name
IN KINDFUL
5000 `// Kindful ID`	Pete	B

Kindful also stores a mapping table linking our Kindful ID to all identifiers passed in via all API applications connected to an organization account.

In our example, the mapping table may look like this:

id	contact_id	external_id
`#{some id}`	5000	1

Later, if the record needs to be updated, an import request can be made with the action_type= update by passing in:

id	first_name	last_name
YOUR REQUEST
1 `// your external_id`	Pete	Brumm

Then, Kindful will match (by default) on external_id for the contact unless you specify a different match_by parameter, and Kindful would apply that update to it's internal record.

id	first_name	last_name
IN KINDFUL
5000 `// Kindful ID`	Pete	B`rumm // Last Name Updated`

NOTE

When updating records, it is best to provide an updated_at field. This field is used to determine if an Admin user already made changes to those records before a request made via the API is applied.

For example, if the above last_name had been changed by an Admin user in the evening but your API request timestamp was from the morning; when you send the updates the next day via the API, the Admin user's changes to that field would trump your API request. Other fields could get applied if they weren't changed.

This allows the developer to not worry about constantly undoing an admin's changes.

Matching Options

There are various ways you can match_by by each format type.