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
• Choosing an format_type
• match_by Behavior
• Large Batch Imports

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:

Sample Create Request with action_type

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

}

Sample Create Request without action_type

{
  "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 Customer API Reference

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.

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 in your request data. 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

{
  "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 Customer 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.

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).