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 or /imports/multi 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" and passing in an id for all records you create via the import API so that you can subsequently update records via your third party system's id.

Import Actions Types

First, let's expand a little on what behavior you're able to affect with the "action_type" import parameter.

option
behavior
If a match is found
if no match is found

create

The system will search for an existing record with the same identifier specified in the "match_by" parameter.

If the "match_by" parameter is not specified in the request, then "external_id" is used.

The record is ignored. Kindful is not updated.

Note that if the same id appears more than once in the same request, all of the data from each record will be merged into one record.

a new record is created

update

The system will search for an existing record with the same identifier specified in the "match_by" parameter.

If the "match_by" parameter is not specified in the request, then "external_id" is used.

The system looks up the last modified time of the record (consulting both applied updates and unapplied updates).

If the latest updated_time in Kindful is greater than the updated_time of the request, the record is ignored. Kindful is not updated.

However, if the latest updated_time in Kindful is less than the updated_time of the request, the record is updated.

A new record will be created.

Example Usage

Let's say you send the following API request to Kindful:

{
  "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 take the id 123 and use this to match against our application integration table. If this record exists, then Kindful already has a record of this and will not create it again.

This enables the developer to pass in 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 Kindful's.

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

1

Pete

B

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

So, Kindful would have the below contact record:

id
first_name
last_name

5000

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 to be updated, an import request can be made with the action_type=update by passing in:

id
first_name
last_name

1

Pete

Brumm

Then Kindful will match (by default) on external_id for the contact,

...
match_by: {contact: "external_id"}
...

and Kindful would apply that update to it's internal record.

id
first_name
last_name

5000

Pete

Brumm

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.