2-way Sync
For a two-way sync you'll need both Querying and Linking set up. See the following docs for more info:
The following are required for a successful 2-Way Sync between Applications. Before attempting these requests, ensure that you have set up your environment.
Examples below make requests to the Sandbox.
For requests to PRODUCTION, use https://app.kindful.com/api/v1/imports
Import Records Into Kindful
Use the Imports API to import records into Kindful. Each record you import into Kindful will create an external_id from your id for that record.
It is important that you send an ID with your records so they can be easily identified by your application for CRUD.
Send Data to Kindful
Make a POST request to https://app-sandbox.kindful.com/api/v1/imports with the following in the body:
{
"data_format": "contact",
"action_type":"create",
"data_type":"json",
"data":
[
{
"id":"id_01", // the ID from your application (becomes external_id)
"title": "Mr.",
"first_name": "John",
"last_name": "Example",
"gender": "M",
"employer": "Acme, Inc.",
"email": "jsmith@email.co",
"alt_email": "johnsmith@email.co",
"addr1": "123 ABC Ln.",
"addr2": "Apt. 1001",
"city": "Nashville",
"state": "TN",
"postal": "37206",
"country": "United States",
"birthday": "1985/02/13",
"primary_phone": "555-555-5555",
"alt_phone": "555-555-5555",
"fax_phone": "555-555-5555",
"spouse_first": "Jane",
"spouse_last": "Smith",
"created_at": "2015-10-13 18:56:12 UTC"
}
]
}Sample Response
{
"id": "367cc5b6-982b-49ec-8b3d-416d4f246814",
"status": "pending"
}Retrieve Records from Kindful
Query Kindful for Data
Make a contact query for "not_linked" records by a POST request to https://app-sandbox.kindful.com/api/v1/contacts/query to retrieve records in Kindful that your application "doesn't know about" with the following in the body. Kindful's API returns records without your External ID.
{
"query":
[
"not_linked"
]
}Sample Response
{
"page": 1,
"query_token": "tok_289c2fd56e92f4ae",
"results": [
{
"id": 230465,
"external_id": null,
"sync_version": 1,
"donor_type": "Person",
"title": null,
"first_name": "Not",
"last_name": "Linked",
"gender": "U",
"birthday": "1985/02/13",
"company_name": null,
"employer": null,
"retired_or_not_employed": false,
"occupation": null,
"email": "notlinked@kf.com",
"alt_email": null,
"email_opt_in": true,
"email_deliverable": true,
"email_deliverable_error_reason": null,
"primary_phone": "",
"alt_phone": null,
"fax_phone": null,
"addr1": "123 Test Lane",
"addr2": "",
"city": "Tester",
"state": "TN",
"postal": "37204",
"country": "United States",
"spouse_first": "",
"spouse_last": "",
"created_at": "2019-05-02T14:42:20.075-05:00",
"updated_at": "2019-05-02T14:42:40.873-05:00",
"custom_fields": {},
"record_type": "contact",
"_links": {
"self": "https://af653-playground.kindful.com/admin/contacts/230465"
}
}
],
"has_more": false
}Send Unlinked Records to Kindful
Via an Import request using the action_type of update, add your External ID to any records that don't have it.
Each record that you send must at the very least include First Name, Last Name, Email Address and ID.
Make a POST request to https://app-sandbox.kindful.com/api/v1/imports with the following in the body:
{
"data_format": "contact",
"action_type":"update", // will create a contact if does not exist or will update contact if it does exist
"data_type":"json",
"data":
[
{
"id":"id_02", // the ID from your application (becomes external_id)
"first_name": "Not",
"last_name": "Linked",
"gender": "U",
"birthday": "1985/02/13",
"email": "notlinked@kf.com",
"addr1": "123 Test Lane",
"city": "Tester",
"state": "TN",
"postal": "37204",
"country": "United States",
"created_at": "2019-05-02T14:42:20.075-05:00",
"updated_at": "2019-05-02T14:42:40.873-05:00",
}
]
}Get Updated Records from Kindful
Make a POST request to https://app-sandbox.kindful.com/api/v1/contacts/query with the following in the body:
{
"query":
[
"changed"
]
}Sample Response
{
"page": 1,
"query_token": "tok_160321a4727d6a6a",
"results": [
{
"id": 230462,
"external_id": "id_01",
"sync_version": 2, // Kindful checks the sync_version to see if a record has been updated.
"donor_type": "Person",
"title": "Mr.",
"first_name": "John",
"last_name": "Smith",
"gender": "M",
"birthday": "1985/02/13",
"company_name": null,
"employer": "Acme, Inc.",
"retired_or_not_employed": false,
"occupation": "",
"email": "jsmith@email.co",
"alt_email": "johnsmith@email.co",
"email_opt_in": true,
"email_deliverable": true,
"email_deliverable_error_reason": null,
"addr2": "Apt. 1001",
"city": "Nashville",
"state": "TN",
"postal": "37206",
"country": "United States",
"birthday": "1985/02/13",
"primary_phone": "555-555-5555",
"alt_phone": "555-555-5555",
"fax_phone": "555-555-5555",
"spouse_first": "Jane",
"spouse_last": "Smith",
"created_at": "2015-10-13 18:56:12 UTC",
"updated_at": "2019-05-02T14:42:55.085-05:00",
"custom_fields": {},
"record_type": "contact",
"_links": {
"self": "https://af653-playground.kindful.com/admin/contacts/230462"
}
}
],
"has_more": false
}Stay in Sync
Track updates in your system and when necessary, update Kindful records via the Imports API, matching by your External ID.
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).