- Create and update contact, transaction and other activity records
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
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
Create a New Record
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:
Create a New Record
Choose your format_type based upon what types of record(s) you want to create in Kindful:
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
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.
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?
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 firstname.lastname@example.org, 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).
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.
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).
|Record Matching Overview|