Introduction to Imports

You can use the Kindful API to import data into a Kindful account. More specifically, you can create and update contact, transaction and other activity records.

There are several things to consider when importing into Kindful:

Choosing an action_type

Before queueing your import, the Kindful API will attempt to identify an existing record using record matching either by specified match_by parameters or the default external_id if you do not specify any match_by parameters. After this attempt, the action_type you send with your request will determine what happens next.

There are two (2) action_types:

  • Create only creates records that don't already exist in Kindful (default)
  • Update can be used to create or update records in Kindful

The table below gives a bit more information on what happens when using one of the two (2) action_types:

action_type 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.		 Creates a New Record
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.		 Creates a New Record

Sample Create Request with action_type

COPY 
{
  "data_format": "contact",
  "data_type": "json",
  "action_type": "create",
  "data": [
    {
      "id": "123",
      "first_name": "Pete",
      "last_name": "Brumm"
    }
  ]

}

Sample Create Request without action_type

COPY 
{
  "data_format": "contact", // would use default create `action_type`
  "data_type": "json",
  "data": [
    {
      "id": "123",
      "first_name": "Pete",
      "last_name": "Brumm"
    }
  ]

}

See more sample requests in the Kindful Partner API Reference

Choosing an format_type

Choose a format_type based upon what types of record(s) you want to create in Kindful. The table below shows the format types available and each type is linked to sample requests from the Kindful API Reference.

format_type Supported Record Types
contact Contacts
contact_with_transaction Contacts, Transactions, or Contacts and Transactions
contact_with_note Contacts, Notes, or Contacts and Notes
contact_with_pledge Contacts, Pledges, or Contacts and Pledges
contact_with_non_cash_gift Contacts, Non-Cash Gifts, or Contacts and Non-Cash Gifts
contact_with_soft_credit Contacts, Soft Credits, or Contacts and Soft Credits
contact_with_cause_team
split_transaction

match_by Behavior

When using /imports, you'll need to tell Kindful to how handle contact matching for purposes of:

  • Preventing duplicate records
  • Updating existing records

By default, the Kindful API attempts to find an existing record in Kindful using your (API Application-specific) External ID. The API Application External ID is the "id" field from your application's database. Other integrations may have their own external_id but your application will only see your application's id. To learn more about record matching, see the Record Matching Overview.

Sample request with record_matching

COPY 
{
  "data_format": "contact",
  "data_type": "json",
  "action_type": "update",
  "match_by":
  	{
    "contact": "external_id"
  	},
  "data":
  	[
      {
        "id": "123", // becomes the external_id
        "first_name": "Pete",
        "last_name": "Brumm",
        "created_at": "2015-09-29 17:23:49 +0000"
      }
    ]
}

See more sample requests in the Kindful Partner API Reference

Choosing to override the default match_by behavior

We offer several ways to override the default record matching behavior through the match_by parameter:

  • look for a record with the same External ID,
  • look for a record with a matching Email Address,
  • look for a record whose First Name, Last Name, and Email address all match

Overriding the default record-matching behavior

Let's say you have a list of contact records that you want to import into Kindful using the Kindful API. You suspect that some of those contacts already exist in Kindful (having been created manually or through another data source), and you only want to create contacts that don't already exist in Kindful.

If you send a create request with match_by = first_name_last_name_email and an exact match is found for all three of those fields, nothing happens. Otherwise, a new record would be created.

It's still possible that you could create duplicates.

For Example

If your dataset contains Sue McKindly smckindly@email.com, and Kindful contains Sue McKindly (with no email address), a new record would be created.

A data expert could examine records within Kindful and choose to merge them or not within the user interface (based upon their specific knowledge of their data).

Large Batch Imports

If sending in a large batch of records through the Kindful API, we recommend sending in batches of 10k records at a time. This will need to be done via csv data type format (sent as URLs).

Things to Consider for Large Batch Imports:

  • We assume utf-8 encoding
  • Supported data types include csv and json

Using csv

If you plan to use the csv data type, make sure the file does not contain BOM fields. These fields are usually added by the Excel application when saving an Excel file to csv format.

Import Record Limits

We limit records in the body of the request to 100. If sending a URL to a JSON file there is no limit, although limiting to batches of 10k would be ideal (a single json object per line, and not a single json array).