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.
- Retrieve Contacts
- Linked or Changed Example
- Body Params
- Supported Query Types/Query Parameters
- Available Columns
- What could cause a contact to become "un-linked"?
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
{
"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