Querying - Transaction 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 Transactions

  • Not Linked Transactions (Transactions that are not linked to your 3rd party application)
  • Linked Transactions (Transactions that are linked to your 3rd party application)
  • Out of Sync Transactions (Transactions that are linked but "out of sync" with your 3rd party application)
  • Transactions based upon specific criteria (Transactions within a date range)

Initial Example

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

COPY 
{
  "query": [
      "changed"
  ],
  "per_page": 5,
  "columns": {
    "transaction": ["id", "external_id", "sync_version", "contact_id", "amount_in_cents", 
                    "transaction_time", "campaign", "fund", "updated_at", "batch_id"],
    "contact": ["id", "external_id","sync_version", "first_name", "last_name", "sync_version"],
    "campaign": ["id", "external_id", "sync_version","name"],
    "fund": ["id", "external_id","sync_version", "name"]
  },
  "contact_custom_fields": [1,2] 
}

We have these parameters for transaction ["linked", "changed", "not_linked", "campaign_id", "after", "before"]

Body Params

BODY PARAMS
query
array of mixed types		 for example, "linked" or "not_linked", "changed"
columns
object		 a hash of arrays for each model type you want returned. ["all"] is accepted if all results are wanted for the model. transaction, campaign, fund, designation, contact and contact_custom_field 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.

The has_more key is important to pay attention to when querying and paging through results.

If load is high or the query is slow, the API will return empty results, but still have the hasmore set to true. If this occurs then you should add a delay and then try again to get the results. A delay between 5 and 10 seconds should be sufficient. An estimatedresults_delay will be specified to help reduce the number of requests.

Supported Query Types / Query Parameters

Use query types to filter down which records you want to receive. Below are the query types supported.

Query Keyword min_inputs max_inputs example description additional
linked 0 0 "linked" returns all linked records (records that have added through the API import process with default "external_id" as the match_by alternate format would be {"linked": []} which allows to be combined with other queries
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. In this case you need not specify "linked" as a query param.
after 1 1 {"after": "2016/07/15"} finds all transactions after day. This is filtered in orgs timezone.

accepted formats: yyyy/mm/dd
yyyy-mm-dd
before 1 1 {"before": "2016/07/15"} finds all transactions after day. This is filtered in orgs timezone.

accepted formats: yyyy/mm/dd
yyyy-mm-dd		 can be combined with "after" to enforce both in an "AND" {"after": "2016/07/13", "before": "2016/07/20"}
or 1 no limit { "or": ["not_linked", "changed"]}

{"or": ["linked", {"after": "2016/01/13"}]}		 allows one or other criteria to match
and 1 no limit {"and": ["not_linked", {"after": "2016/01/13"}]} mainly used within nested or statements also multiple keys in a hash is also treated as an AND as in the {"after": "2016/07/13", "before": "2016/07/20"} example. It must match both. the top level query is an implicit and so "query": ["not_linked", {"after": "2016/01/13"}] is equivalent to "query": [{"and": ["not_linked", {"after": "2016/01/13"}]}]
not 1 no limit {"not": ["changed"]} Inverts the search
campaign_id 1 no limit {"campaign_id": "1"}
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.

Transactions Query API Reference

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