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

2waysync

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:

COPY
{
"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

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

COPY
{
   "query": 
   [
       "not_linked"
   ]
}

Sample Response

COPY
{
    "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:

COPY
{
"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:

COPY
{
   "query": 
   [
       "changed"
   ]
}

Sample Response

COPY
{
    "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).