Querying - Contact Queries

You may want to retrieve contacts from Kindful so that you can import them into a complimentary third party system (Email Marketing, etc). Or, if you're implementing a two-way sync, query Kindful for an Organization's new or changed transactions to stay in-sync.

For a two-way sync you'll need both Querying and Linking set up. Check out the transactions/link and contact/link docs too.

Retrieve Contacts

  • Not Linked Contacts (Contacts that are not linked to your 3rd party application)
  • Linked Contacts (Contacts that are linked to your 3rd party application)
  • Out of Sync Contacts (Contacts that are linked but "out of sync" with your 3rd party application)
  • Contacts based upon specific criteria (Contacts in a Group, etc.)

Linked or Changed Example

POST: https://app.kindful.com/admin/oauth2/api/v1/contacts/query

COPY
{
  "query": [
      "linked",  
      "changed",
      {"not": [
        {"by_group_id": [1234]}
      ]}
  ],
  "per_page": 5,
  "custom_fields": [1,2],
  "columns": {
    "contact": ["id", "external_id","sync_version", "first_name", "last_name"]
  }
}

We have these parameters for contact [ "linked", "changed", "not_linked", "by_group_id", "has_email", "near_postal"]


Body Params

BODY PARAMS
query
array of mixed types
See complete list of query types below with example usage
columns
object
a hash of arrays for each model type you want returned. ["all"] is accepted if all results are wanted. custom_field, contact are relevant keys for this model
custom_fields
array of strings
list of custom field ids to return. can be ['all', 'linked'] or a list of the ids
per_page
int32
50 is max and default page size
query_token
string
query token is needed to step through pages. It would be blank on first request. The query, columns, custom_fields are not required on subsequent requests. The query token expires on inactivity of 5 minutes.

Supported Query Types / Query Parameters

Use the following parameters in your query to further limit which Contacts you receive from Kindful.

Query Keyword min_inputs max_inputs example description
linked 0 0 "linked" returns all records associated with the integration (records that were added through the API import process with default "external_id" as the match_by, or records in Kindful whose application-specific external_id has been populated (therefore "linking" the record to your API application)
not_linked 0 0 "not_linked" returns all records without your application-specific External ID (conceptually "new" records)
changed 0 0 "changed" only applies to linked records that are out of sync due to updates. (Linked records whose current version field is out of sync with your application's "known version"
or 1 no limit { "or": ["not_linked", "changed"]}

{"or": ["linked", {"after": "2016/01/13"}]}
and 1 no limit {"and": ["not_linked", {"after": "2016/01/13"}]}
not 1 no limit {"not": ["changed"]} Inverts the search
by_group_id 1 no limit {"by_group_id": "23"} Will return only contacts in the specified group, based upon group ID.

See Groups Metadata Query for info on how to retrieve all groups (and group IDs) in the account.
near_postal 1 no limit { "query": [{"near_postal": ["37212","50"]}], "per_page": 5 } Pass in 2 parameters, the zipcode and a range (in miles). For example: [“37027”, 5] would return all contacts within 5 miles of 37027.
has_email 1 no limit "has_email": "Yes" Returns contacts that have or do not have email addresses in Kindful.

Available Columns

The following columns are available via the API. All columns are returned by default unless specific columns are requested in the query.

- id
- external_id
- sync_version
- donor_type
- title
- first_name
- last_name
- gender
- birthday
- company_name
- employer
- retired_or_not_employed
- occupation
- email
- alt_email
- email_opt_in
- email_deliverable
- email_deliverable_error_reason
- primary_phone
- alt_phone
- fax_phone
- addr1
- addr2
- city
- state
- postal
- country
- spouse_first
- spouse_last
- created_at
- updated_at
- custom_fields (sub-array)

What could cause a contact to become "un-linked"?

A contact could become un-linked or, in other words, change sync versions if there has been a change in any one of these fields on a contact record in Kindful:

- first_name
- middle_name
- last_name
- organization_name
- address
- address2
- city
- state
- postal_code
- country
- letter_name
- letter_informal
- title
- name_prefix
- name_suffix
- preferred_name
- email
- alt_email
- website
- phone
- phone2
- phone3
- mobile_phone
- work_phone
- fax
- employer
- spouse_first_name
- spouse_last_name
- contact_info
- spouse_phone
- spouse_email
- spouse_occupation
- spouse_email_opt_in
- other_mail_opt_in
- solicitation_opt_in
- news_letter_opt_in
- acknowledgement_opt_in
- gender
- marital_status_id
- address_deliverable
- email_deliverable
- created_at
- parent_id
- active
- retired_or_not_employed
- profession

Contact Query API Reference

To see more examples and requests, see the Contact Query API Reference