Introduction to Imports

Use the Kindful Imports API to:

  • Create and update contact, transaction and other activity records

Configuring your Import Request

A brief overview of some key Imports API parameters follows:

  • Choose an action_type
  • Choose a format_type
  • Choose to override the default match_by behavior

Choosing an action_type

Before queueing your import, the Imports API will attempt to identify existing records in Kindful. What happens next depends on the action_type and (possibly) time stamps associated with your record.

There are 2 action_types:

  • Update can be used to create or update records in Kindful, whereas (most common)
  • Create only creates records that don't already exist in Kindful
action_type
Behavior if a matching record is Found
Behavior if NO matching record is Found

create

Do Nothing

Create a New Record

update

Check Time Stamps:

If the Time Stamp of the Import Request is More Recent than the last Update in Kindful:
Update the Record

If the Time Stamp of the Import Request is Older than the last Update in Kindful:
Do Nothing

Create a New Record

Choosing a format_type

Choose your format_type based upon what types of record(s) you want to create in Kindful:

format_type
Supported Record Types

Contacts

Contacts, Transactions, or Contacts and Transactions

Contacts, Notes, or Contacts and Notes

Contacts, Pledges, or Contacts and Pledges

Contacts, Non-Cash Gifts, or Contacts and Non-Cash Gifts

Contacts, Soft Credits, or Contacts and Soft Credits

Contact record-matching using match_by

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

  • Preventing duplicate records
  • Updating existing records

Default behavior

By default, the Kindful Imports 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 in your request data. Other integrations may have their own external_id but your application will only see your application's id.

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 via the Imports 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 sent a create request with match_by = first_name_last_name_email, then if an exact match is found of all 3 of those fields, then 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).

Good to know

  • 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

To send in the rows in the data field within the request, we limit that 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).