contact

Import contacts with a single file or json data

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
  "data_format": "contact",
  "data_type": "json",
  "action_type": "create",
  "data": [
    {
      "id": "123",
      "first_name": "Pete",
      "last_name": "Brumm"
    }
  ]

}
{
  "data_format": "contact", // would use default create action_type
  "data_type": "csv",
  "data_url": "https://upload-kindful-com.s3.amazonaws.com/uploads/test/5ea4ae63-fd0...",
  "encrypted": "true"
}
{
  "data_format": "contact",
  "data_type": "json",
  "action_type": "update",
  "match_by": 
  	{
    "contact": "external_id"
  	},
  "data": 
  	[
      {
        "id": "123",
        "first_name": "Pete",
        "last_name": "Brumm",
        "created_at": "2015-09-29 17:23:49 +0000"
      }
    ]
}
{
  "data_format": "contact_with_transaction",
  "data_type": "json",
  "action_type": "update",
  "match_by": {
    "contact": "external_id",  // see list below for supported 
    "transaction": "external_id"
  },
  "update_exceptions": {
    "contact": "create" // will allow the transaction data to get updated, but will ignore any updates to contact information.   this is useful for cases where you don't have an updated_at field or when you know your information is probably stale for that table. could be "insert", "update"
  },
  "data": [
    {
      "id": "123",
      "first_name": "Pete",
      "last_name": "Brumm",
      "transaction_id": "467",
      "campaign": "General",
      "amount_in_cents": 200,
      "transaction_time": "2015-10-13 18:56:12 UTC",
      "transaction_updated_at": "2015-10-13 18:56:12 UTC"
    }
  ]

}
{
  "data_format": "contact_with_transaction",
  "data_type": "json",
  "action_type": "update",
  "match_by": {
    "contact": "external_id",  // see list below for supported 
    "transaction": "external_id"
  },
  "update_columns_except": {
    "contact": ["last_name"] // will skip last_name when updating records
  },
  "data": [
    {
      "id": "123",
      "first_name": "Pete",
      "last_name": "Brumm",
      "transaction_id": "467",
      "campaign": "General",
      "amount_in_cents": 200,
      "transaction_time": "2015-10-13 18:56:12 UTC",
      "transaction_updated_at": "2015-10-13 18:56:12 UTC"
    }
  ]
}
{
  "data_format": "contact_with_transaction",
  "data_type": "json",
  "action_type": "update",
  "match_by": {
    "contact": "external_id",  // see list below for supported 
    "transaction": "external_id"
  },
  "update_columns_only": {
    "contact": ["last_name"] // will only update last_name column
  },
  "data": [
    {
      "id": "123",
      "first_name": "Pete",
      "last_name": "Brumm",
      "transaction_id": "467",
      "campaign": "General",
      "amount_in_cents": 200,
      "transaction_time": "2015-10-13 18:56:12 UTC",
      "transaction_updated_at": "2015-10-13 18:56:12 UTC"
    }
  ]
{
  "data_format": "contact",
  "data_type": "json",
  "action_type": "create",
  "custom_fields": ["Hours Worked"],
  "data": [
    {
      "id": "100688",
      "first_name": "Joel",
      "last_name": "Smith",
      "Hours Worked": "32"
    }
  ]
}
A binary file was returned

You couldn't be authenticated

{
  id: "69eea3a6-302b-4219-8d13-e3dc2e392e86",
  status: "pending"
} 
{
  status: "error",
  message: "Too many rows specified in data request
  validation_messages: [
    "Couldn't find contact information for transaction"
  ]
}

Body Params

data_format
string

Tag to specify what type of data is being provided. See Import Formats.

action_type
string

Specifies what action to take with the data. The value can be "create" or "update". If update is specified and new rows are found, Kindful will insert those rows on the contact/s. If existing rows are found those records will update if they haven't been further changed inside Kindful. Change is tracked by an updated_time tag that you can specify in the imports. This is time the record was updated on the organization account and if greater than local updated time we will override.

match_by
object

This defaults for all record types to external_id. See "Record Matching Options".

update_exceptions
object

Allows you to specify that you want to possibly only update transactions and not contacts. See example below.

data_url
string

URL to the data. Ideally this would be a URL that expires after a short time and/or is encrypted. This is required unless data tag is specified.

data_type
string

Supported types include csv and json. This is unnecessary if data param is specified. **Please ensure that if passing in csv that it does not contain BOM fields (It is usually added by excel when saving an excel file as csv and doesn't get added when code programmatically creates it.)

data
array

JSON array data with keys that match the import_format. This is limited to 100 records per call. If POST format type is JSON then this can be provided as an array. This is required unless data_url tag is specified.

compression
string

Supported types: gzip

custom_fields
array of strings

Additional column names provided that need to be mapped to custom fields on the contact record in Kindful.

update_columns_except (coming soon)
object

Only the specified columns will attempt to be updated on the contact record.

update_columns_only (coming soon)
object

Provides ability to specify only specific columns to apply on update.

encrypted (coming soon)
boolean

Indicates whether or not it has been gpg encrypted to kindful's gpg key.

webhook_status_url (coming soon)
string

Provides callback updates as the status changes (coming soon).

chapter_id (coming soon)
string

Provides the ability to apply an import to a chapter instead of the parent organization. See Chapters API for a list of chapters.

custom_field_identifiers (coming soon)
array of strings

Additional column names that are mapped to kindful custom field IDs. Use the /custom_fields API call to receive a list of active custom fields.

 

The id field is an (API) application-specific field and is used to prevent duplicates when multiple applications are connected to the same Organization account.

For more information about creating and updating records, please see Intro to Record Matching

If id is not provided then:
To remove duplicates, we match based upon an exact match of first_name + last_name + email or company_name + email.
This is not ideal, so specify an identifier if at all possible.

columns
required
notes
example
type

id

No

Contact ID

123ABC

String (between 1 and 255 characters)

first_name

Yes unless company_name is populated

for individuals

last_name

Yes unless company_name is populated

for individuals

String (between 1 and 255 characters)

company_name

Yes unless first and last name are populated

For Organization Contacts, this field must be populated.

And if this field is populated, First and last name can be blank in this case. However, if you specify First and Last Name, (in addition to company_name) then those values will populate the "Primary Contact Name" on the Organization record.

String (between 1 and 255 characters)

employer

No

Name of the employer of the contact

email

No

valid email address

String (between 1 and 255 characters)

alt_email

No

valid email address

String (between 1 and 255 characters)

addr1

No

String (between 1 and 255 characters)

addr2

No

String (between 1 and 255 characters)

city

No

String (between 1 and 255 characters)

state

No

state abbreviation TN,NY (not case-sensitive)

String (between 1 and 255 characters)

postal

No

valid country postal code. 5 digits if United States

String (between 1 and 255 characters)

country

No

United States

http://www.worldatlas.com/aatlas/ctycodes.htm the full name from the list above. the A2 (ISO) code also can be used.

title

No

(position or job title)

String (between 1 and 255 characters)

birthday

No

yyyy/mm/dd
mm/dd/yyyy
yyyy-mm-dd
mm-dd-yyyy

String (between 1 and 255 characters)

primary_phone

No

digits or with () - -

String (between 1 and 255 characters)

alt_phone

No

String (between 1 and 255 characters)

fax_phone

No

String (between 1 and 255 characters)

spouse_first

No

String (between 1 and 255 characters)

spouse_last

No

String (between 1 and 255 characters)

gender

No

Male = M, Female=F, Unknown=U. if blank the gender will be guessed based on name

M

M/F/U

created_at

No

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

updated_at

No
Yes if action = update

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

occupation

No

Dentist

String (between 1 and 255 characters)

retired_or_not_employed

No

True/False or Yes/No

True

True/False/Yes/No

email_opt_in

No

True/False

True

Boolean

email_deliverable

No

True/False

True

Boolean

email_deliverable_error_reason

No

Soft Bounce

String (between 1 and 255 characters)

Email Deliverable Params

'email_opt_in', 'email_deliverable' and 'email_deliverable_error_reason' are available params on all contact import types.

Creating Groups

 

Groups can be created on the fly while using any of the Contact Import types and performing a match_by group name. When you pass in a name for the new group, Kindful will assign the group ID.

You can query for groups to the get the group ID.

Creating Events

 

Events can be created on the fly while using the contact_with_transaction Import API and performing a match_by event name or match_by event id - although, Kindful recommends that you create events by event name so that a logically named event exists in the database, allowing Kindful to assign the initial Event ID.

View the documentation for this here: https://developer.kindful.com/v1.0/docs/event

contact_with_transaction

Use this format for importing contact and transaction data in one record into a Kindful Organization account

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
"data_format": "contact_with_transaction",
"action_type":"create",
"data_type":"json",
    "data": 
 [
    {
    "id":"123456",
    "title": "Mr.",
    "first_name": "John", // Not required if company_name is used
    "last_name": "Smith", // Not required if company_name is used
    "company_name": "Acme, Inc.", // Not required if first_name and last_name is used
    "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": "07/29/1985",
    "primary_phone": "555-555-5555",
    "alt_phone": "555-555-5555",
    "fax_phone": "555-555-5555",
    "spouse_first": "Jane",
    "spouse_last": "Smith",
    "stripe_customer_id": "",
    "authorize_customer_id": "",
    "paypal_payer_id": "",
    "created_at": "2015-10-13 18:56:12 UTC",
    "transaction_id": "987654",
    "amount_in_cents": "5000",
    "currency": "usd",
    "transaction_time": "2015-10-13 18:56:12 UTC",
    "campaign": "General",
    "campaign_id": "123abc",
    "fund": "General",
    "fund_id": "456def",
    "acknowledged": "true",
    "transaction_note": "This is a transaction note",
    "stripe_charge_id": "",
    "authorize_transaction_id": "",
    "paypal_transaction_id": "",
    "transaction_type": "Cash",
    "was_refunded": "false",
    "check_num": "",
    "card_type": "Mastercard",
    "non_tax_deductible_amount_in_cents": "500",
    "is_donation": "true",
    "cause": "General",
    "cause_id": "12345",
		"team": "Team John",
	  "team_id": "12345", 
  	"team_member_first_name": "John", 
	  "team_member_last_name": "Smith", 
	  "team_member_id": "12345"
   } 
 ]

}

{
"data_format": "contact_with_transaction",
"action_type":"create",
"data_type":"json",
    "data": 
 [
    {
    "id":"123456",
    "title": "Mr.",
    "first_name": "John", // Not required if company_name is used
    "last_name": "Smith", // Not required if company_name is used
    "company_name": "Acme, Inc.", // Not required if first_name and last_name is used
    "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": "07/29/1985",
    "primary_phone": "555-555-5555",
    "alt_phone": "555-555-5555",
    "fax_phone": "555-555-5555",
    "spouse_first": "Jane",
    "spouse_last": "Smith",
    "stripe_customer_id": "",
    "authorize_customer_id": "",
    "paypal_payer_id": "",
    "created_at": "2015-10-13 18:56:12 UTC",
    "transaction_id": "987654",
    "amount_in_cents": "5000",
    "currency": "usd",
    "transaction_time": "2015-10-13 18:56:12 UTC",
    "campaign": "General",
    "campaign_id": "123abc",
    "parent_campaign": "Events", // Use for organizing campaigns into categories
    "parent_campaign_id": "123abc",
    "fund": "General",
    "fund_id": "456def",
    "acknowledged": "true",
    "transaction_note": "This is a transaction note",
    "stripe_charge_id": "",
    "authorize_transaction_id": "",
    "paypal_transaction_id": "",
    "transaction_type": "Cash",
    "was_refunded": "false",
    "check_num": "",
    "card_type": "Mastercard",
    "non_tax_deductible_amount_in_cents": "500",
    "is_donation": "true",
    "cause": "General",
    "cause_id": "12345",
		"team": "Team John",
	  "team_id": "12345", 
  	"team_member_first_name": "John", 
	  "team_member_last_name": "Smith", 
	  "team_member_id": "12345"
   } 
 ]

}

{
"data_format": "contact_with_transaction",
"action_type":"create",
"data_type":"json",
    "data": 
 [
    {
    "id":"123456",
    "title": "Mr.",
    "first_name": "John", // Not required if company_name is used
    "last_name": "Smith", // Not required if company_name is used
    "company_name": "Acme, Inc.", // Not required if first_name and last_name is used
    "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": "07/29/1985",
    "primary_phone": "555-555-5555",
    "alt_phone": "555-555-5555",
    "fax_phone": "555-555-5555",
    "spouse_first": "Jane",
    "spouse_last": "Smith",
    "stripe_customer_id": "",
    "authorize_customer_id": "",
    "paypal_payer_id": "",
    "created_at": "2015-10-13 18:56:12 UTC",
    "transaction_id": "987654",
    "amount_in_cents": "5000",
    "currency": "usd",
    "transaction_time": "2015-10-13 18:56:12 UTC",
    "campaign": "General",
    "campaign_id": "123abc",
    "fund": "General",
    "fund_id": "456def",
    "acknowledged": "true",
    "transaction_note": "This is a transaction note",
    "stripe_charge_id": "",
    "authorize_transaction_id": "",
    "paypal_transaction_id": "",
    "transaction_type": "Cash",
    "was_refunded": "false",
    "check_num": "",
    "card_type": "Mastercard",
    "non_tax_deductible_amount_in_cents": "500",
    "is_donation": "true",
   "occupation": : "Dentist",
   "retired_or_not_employed": "False"
   } 
 ]

}

A binary file was returned

You couldn't be authenticated

{
  id: "69eea3a6-302b-4219-8d13-e3dc2e392e86",
  status: "pending"
} 
{
  status: "error",
  message: "Too many rows specified in data request
  validation_messages: [
    "Couldn't find contact information for transaction"
  ]
}

Body Params

data_format
string
action_type
string
data_type
string
 

The id field is an (API) application-specific field and is used to prevent duplicates when multiple applications are connected to the same Organization account.

For more information about creating and updating records, please see Intro to Record Matching

If id is not provided then:
To remove duplicates, we match based upon an exact match of first_name + last_name + email or company_name + email.
This is not ideal, so specify an identifier if at all possible.

If a transaction_id isn't provided then we will generate a guid for it, to be used internally.

columns
required
notes
example
type

id

No

Contact ID

123ABC

String

first_name

Yes unless company_name is populated

last_name

Yes unless company_name is populated

String

company_name

Yes unless first and last name are populated

Use company_name if the contact is not an individual but a company. First and last name can be blank in this case, if you specify First and Last Name, this will be the Primary Contact Name on the Organization Record.

String

employer

No

Company that individual works for

email

No

valid email address

String

alt_email

No

valid email address

String

addr1

No

String

addr2

No

String

city

No

String

state

No

state abbreviation TN,NY

String

postal

No

valid country postal code. 5 digits if United States

String

country

No

United States

http://www.worldatlas.com/aatlas/ctycodes.htm the full name from the list above. the A2 (ISO) code also can be used.

title

No

Mr, Ms, Dr

String

birthday

No

yyyy/mm/dd
mm/dd/yyyy
yyyy-mm-dd
mm-dd-yyyy

String

primary_phone

No

digits or with () - -

String

alt_phone

No

String

fax_phone

No

String

spouse_first

No

String

spouse_last

No

String

gender

No

Male = M, Female=F, Unknown=U. if blank the gender will be guessed based on name

M

M/F/U

stripe_customer_id

No

cus_1234

authorize_customer_id

No

customer id in authorize.net's CIM

paypal_payer_id

No

payer_id from Paypal Basic

created_at

No

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

updated_at

No
Yes if action = update and your updating contact

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

transaction_id

No

234DEF

amount_in_cents

Yes

this is in cents. so 500 = $5.00

500

Must be > 0

currency

No

lowercase

usd

transaction_time

Yes

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

1444762572
2015-10-13 18:56:12 UTC
2015-10-13T18:56:12+00:00

transaction_updated_at

No
Yes if action = update

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

If not specified it will be set to transaction_time.

This field is required if an update is being performed

campaign

No

event or category of transaction. Defaults to Partner Name

https://support.kindful.com/hc/en-us/articles/217204108

Gala, General, Mail Appeal

String

campaign_id

No

campaign identifier to minimize duplicates

String

parent_campaign

No

parent_campaign is only needed if you organize your campaigns in a hierarchy (for example, you organize your campaigns into categories). If parent_campaign is provided, it will be the parent of the provided campaign.

Events, Galas

String

parent_campaign_id

No

String

fund

Yes (if unknown, pass 'General')

larger group or fund of where the money ends up
https://support.kindful.com/hc/en-us/articles/217204108

General, Restricted, Africa

String

fund_id

Yes (if unknown, pass '1')

fund identifier to minimize duplicates

String

acknowledged

No

used to determine if additional communication has occurred in addition to a transaction receipt email

Y,N,0,1,true,false

boolean

transaction_note

No

text details about transaction

Text (max 2000 characters)

stripe_charge_id

No

Stripe charge token for identifying charge

ch_12345

String

authorize_transaction_id

No

Authorize Transaction Id

String

paypal_transaction_id

No

Paypal Transaction Id

String

transaction_type

No

Cash
Credit
Check
Paypal
Stock
EFT
Payroll Deduction
Consolidated
Square

Paypal

String

was_refunded

No

If the amount was refunded the same transaction_id can be returned in a subsequent import and be linked to this record. Transactions can't be refunded across separate sheets if transaction_id is not specified

Y,N,0,1,true,false

Boolean

check_num

No

number on the check

card_type

No

credit card type. defaults to blank. if card_type is provided the transaction_type will be defaulted to "credit"

mastercard, master card,visa,discover,amex,american express,

String

non_tax_deductible_amount_in_cents

No

assumed to be zero

Integer

is_donation

No

assumed Yes unless specified

Y,N,0,1,true,false

Boolean

cause

No

General

String

cause_id

No

12345

String

team

No

General

String

team_id

No

12345

String

team_member_first_name

No

John

String

team_member_last_name

No

Smith

String

team_member_id

No

12345

String

occupation

No

Dentist

String

retired_or_not_employed

No

True/False or Yes/No

False

split_transaction

Use this format for adjusting existing transactions and allocating the money to different campaigns or funds

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
  "data_format": "split_transaction",
  "action_type":"create",
  "data_type":"json",
  "data": [
           {
              "id": "1:1",
              "transaction_id":"1",
              "unit_amount_in_cents":"100",
              "quantity": "7",
              "campaign": "Test Campaign 2",
              "campaign_id": "7",
              "fund": "Test Fund 2",
              "fund_id": "8"
            },
            {
              "id": "1:2",
              "transaction_id": "1",
              "unit_amount_in_cents": "300",
              "quantity": "1",
              "campaign": "Test Campaign",
              "campaign_id": "5",
              "fund": "Test Fund",
              "fund_id": "6"
            }
          ]

}

{
  "data_format": "split_transaction",
  "action_type":"create",
  "data_type":"json",
  "data": [
           {
              "id": "1:1",
              "transaction_id":"1",
              "unit_amount_in_cents":"100",
              "quantity": "1",
              "campaign": "Test Campaign 2",
              "campaign_id": "7",
              "fund": "Test Fund 2",
              "fund_id": "8",
              "deleted_at": "2016-10-13T18:56:12+00:00"
            },
            {
              "id": "1:2",
              "transaction_id": "1",
              "unit_amount_in_cents": "25",
              "quantity": "4",
              "campaign": "Test Campaign",
              "campaign_id": "5",
              "fund": "Test Fund",
              "fund_id": "6"
            }
          ]

}


{
  "data_format": "split_transaction",
  "action_type":"create",
  "match_by": {
    "transaction": "id"
  },
  "data_type":"json",
  "data": [
           {
              "id": "17950412:1",
              "transaction_id":"17950412",
              "unit_amount_in_cents":"5000",
              "quantity": "1",
              "campaign": "Split Test 1",
              "campaign_id": "splittest1",
              "fund": "General1",
              "fund_id": "General1"
            },
            {
              "id": "17950412:2",
              "transaction_id": "17950412",
              "unit_amount_in_cents": "623",
              "quantity": "1",
              "campaign": "Split Test 2",
              "campaign_id": "splittest2",
              "fund": "General2",
              "fund_id": "General2"
            }
          ]

}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

data_format
string
action_type
string
data_type
string
 

The id field is an (API) application-specific field and is used to prevent duplicates when multiple applications are connected to the same Organization account.

For more information about creating and updating records, please see Intro to Record Matching

A transaction must exist in Kindful from a prior import or linking

If a transaction_id isn't found then the row will be dropped. Imports occur in the order they are received so it is fine to submit the contact_with_transaction and then the split_transaction before the first has completed.

Splitting A Transaction Created Externally - Using external_id

Split transaction default is to split a transaction using external_id. An example of this can be found below as the primary example.

If external_id is "null" on the transaction you cannot use API defaults and will need to use a match_by as described in the next paragraph.

Splitting A Transaction Created by Kindful - Using transaction_id

You can also split a transaction that has been created by Kindful and does not contain an external ID (in this case the transaction will contain a null status for external_id). In order to do so, you will need to use a match_by pointing towards transaction_id. You can find an example of this below.

ID for split transactions

Kindful stores split transactions in the same table as transactions as well as the link between external_id and transaction_id. If your application stores splits in separate tables be sure that the id's don't overlap.

This can be accomplished by specifying the id as "<trans_id>:<split_id>".

ID overlap

If the id does overlap with an existing transaction it will be dropped and a notification added to GET /imports/<import_id> API call.

Quantities and unit amount must add up to transaction total

If transaction is currently for $100.00 (10000) the total combination of split transactions must add up.

Example:
2000 with quantity of 2
3000 with quantity of 2

columns
required
notes
example
type

id

No

Split transaction id

123ABC see note above.
234DEF:123ABC

String

transaction_id

No

234DEF

unit_amount_in_cents

Yes

this is in cents so 500 = $5.00

500

Must be > 0

quantity

No

integer that defaults to 1

2

campaign

No

event or category of transaction. Defaults to Partner Name

https://support.kindful.com/hc/en-us/articles/217204108

Gala, General, Mail Appeal

String

campaign_id

No

campaign identifier to minimize duplicates

String

parent_campaign

No

parent_campaign is only needed if you organize your campaigns in a hierarchy (for example, you organize your campaigns into categories). If parent_campaign is provided, it will be the parent of the provided campaign.

Events, Galas

String

parent_campaign_id

No

campaign identifier to minimize duplicates

String

fund

Yes (if unknown, pass 'General')

larger group or fund of where the money ends up
https://support.kindful.com/hc/en-us/articles/217204108

General, Restricted, Africa

String

fund_id

Yes (if unknown, send blank or do not specify field)

fund identifier to minimize duplicates

deleted_at

No

Soft deletes the split transaction

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

12345

Time

contact_with_note

import format for sending contact information in notes

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
  "data_format": "contact_with_note",
  "data_type": "json",
  "action_type": "create",
  "data":
  [{
    "id": "1",
    "first_name": "john",
    "last_name": "doe",
    "employer": "kindful",
    "email": "john@kindful.com",
    "alt_email": "john+1@kindful.com",
    "addr1": "1 main st",
    "addr2": "appt 2",
    "city": "nashville",
    "state": "TN",
    "postal": "37215",
    "country": "USA",
    "title": "Mr",
    "birthday": "2015/05/18",
    "primary_phone": "6152605555",
    "alt_phone": "6152606666",
    "fax_phone": "6152607777",
    "spouse_first": "Emi",
    "spouse_last": "Canahuati",
    "gender": "M",
    "created_at": "2015-10-13T18:56:12+00:00",
    "updated_at": "2015-10-13T18:56:12+00:00",
    "campaign": "Test Campaign",
    "campaign_id": "123",
    "fund": "Test Fund",
    "fund_id": "123",  
    "note_id": "1",
    "note_time": "2015-10-13T18:56:12+00:00",
    "note_updated_at": "2015-10-13T18:56:12+00:00",
    "note_type": "General",
    "note_subject": "Subject",
    "note_body": "This is the body of the note. Write things here.",
    "message_body": "This is an alternative body to place note contents. This message body will display as a non-editable body in the UI of Kindful.",
    "note_sender_name": "Tony Perkis",
    "note_sender_email": "heavyweights@kindful.com"
  }]   
}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

data_format
string
action_type
string
data_type
string
 

The id field is specific to the partner and is used to keep duplicates out. The same contact record can be specified multiple times without causing duplicates.

If id is not provided then:
to remove duplicates we perform a first_name + last_name + email or company_name + email. This is not ideal so try to specify an identifier

if a note_id isn't provided then we will generate a guid for it internally

columns
required
notes
example
type

id

No

Contact ID

123ABC

String

first_name

Yes unless company name

String

last_name

Yes unless company name

String

employer

Yes unless first and last name

String

email

No

valid email address

String

alt_email

No

valid email address

String

addr1

No

String

addr2

No

String

city

No

String

state

No

state abbreviation TN,NY

String

postal

No

valid country postal code. 5 digits if United States

String

country

No

United States

http://www.worldatlas.com/aatlas/ctycodes.htm the full name from the list above. the A2 (ISO) code also can be used.

title

No

Mr, Ms, Dr

String

birthday

No

yyyy/mm/dd
mm/dd/yyyy
yyyy-mm-dd
mm-dd-yyyy

String

primary_phone

No

digits or with () - -

String

alt_phone

No

String

fax_phone

No

String

spouse_first

No

String

spouse_last

No

String

gender

No

Male = M, Female=F, Unknown=U. if blank the gender will be guessed based on name

M

M/F/U

created_at

No

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

updated_at

No
Yes if action = update and your updating contact

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

note_id

No

234DEF

message

Yes

text description of note

This is a note

String

note_time

Yes

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

1444762572
2015-10-13 18:56:12 UTC
2015-10-13T18:56:12+00:00

note_updated_at

No
Yes if action = update

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

If not specified it will be set to note_time.

This field is required if an update is being performed

campaign

No

event or category of transaction. Defaults to Partner Name

https://support.kindful.com/hc/en-us/articles/217204108

Gala, General, Mail Appeal

String

campaign_id

No

campaign identifier to minimize duplicates

String

parent_campaign

No

parent_campaign is only needed if you organize your campaigns in a hierarchy (for example, you organize your campaigns into categories). If parent_campaign is provided, it will be the parent of the provided campaign.

Events, Galas

String

parent_campaign_id

No

String

fund

No

larger group or fund of where the money ends up

https://support.kindful.com/hc/en-us/articles/217204108

General, Restricted, Africa

String

fund_id

No

fund identifier to minimize duplicates

String

note_type

No - Default "General"

Call
Event
General
Meeting
Received Email
Received Letter
Recurring Gift Cancelation
Recurring Gift Update
Sent Email
Sent Letter
Visit From
Visit To

Sent Email

String

note_subject

No

String

note_body

No

Text (max 5000 characters)

occupation

No

Dentist

String

retired_or_not_employed

No

True/False or Yes/No

False

message_body

No

This is an alternative body to place note contents. This message body will display as a non-editable body in the UI of Kindful.

Text

note_sender_name

No

To indicate the sender of an email or letter type note

Tony Perkis

Text

note_sender_email

No

To indicate the sender email address of an email type note

heavyweights@kindful.com

Text

contact_with_pledge

import format for sending contact information in with pledges

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
  "data_format": "contact_with_pledge",
  "data_type": "json",
  "action_type": "create",
  "data":
  [{
    "id": "1", 
    "first_name": "john", 
    "last_name": "doe", 
    "employer": "kindful", 
    "email": "john@kindful.com", 
    "alt_email": "john+1@kindful.com", 
    "addr1": "1st Main st", 
    "addr2": "Appt 1", 
    "city": "Nashville", 
    "state": "TN",
    "postal": "37215", 
    "country": "USA", 
    "title": "Mr", 
    "birthday": "2015/5/18", 
    "primary_phone": "6152605555", 
    "alt_phone": "6152606666", 
    "fax_phone": "6152607777", 
    "spouse_first": "Emi", 
    "spouse_last": "Canahuati", 
    "gender": "M", 
    "created_at": "2015-10-13T18:56:12+00:00", 
    "updated_at": "2015-10-15T18:56:12+00:00",
    "campaign": "Test Campaign",
    "campaign_id": "123",
    "fund": "Test Fund",
    "fund_id": "123",
    "pledge_id": "1", 
    "pledge_time": "2015-10-13T18:56:12+00:00", 
    "pledge_updated_at": "2015-10-15T18:56:12+00:00",
    "amount_in_cents": "3000", 
    "pledge_note": "this is a note" 
  }] 
}

A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

data_format
string
action_type
string
data_type
string
 

The id field is specific to the API application you have created on your account. This used to keep duplicates out. The same contact record can be specified multiple times without causing duplicates.

If id is not provided then to remove duplicates we perform a record match by first_name + last_name + email or company_name + email. This is not ideal and poses a risk to your data, so please try to specify an identifier.

If pledge_id is not provided then we will generate a guid for it internally.

columns
required
notes
example
type

id

No

Contact ID

123ABC

String

first_name

Yes unless company_name is populated

If company name is provided, this field will populate the primary contact.

last_name

Yes unless company_name is populated

If company name is provided, this field will populate the primary contact.

String

company_name

Yes unless first and last name are populated

Leave this blank for person records.

String

email

No

valid email address

String

alt_email

No

valid email address

String

addr1

No

String

addr2

No

String

city

No

String

state

No

state abbreviation TN,NY

String

postal

No

valid country postal code. 5 digits if United States

String

country

No

United States

http://www.worldatlas.com/aatlas/ctycodes.htm the full name from the list above. the A2 (ISO) code also can be used.

title

No

Example: Mr., Ms., Dr.

String

birthday

No

yyyy/mm/dd
mm/dd/yyyy
yyyy-mm-dd
mm-dd-yyyy

String

primary_phone

No

digits or with () - -

String

alt_phone

No

String

fax_phone

No

String

spouse_first

No

String

spouse_last

No

String

gender

No

Male = M, Female=F, Unknown=U. if blank the gender will be guessed based on name

M

M/F/U

created_at

No

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

updated_at

No
Yes if action = update and you are updating contact

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

pledge_id

No

234DEF

amount_in_cents

Yes

5000 = $50

5000

currency

No

uppercase

USD

pledge_time

Yes

when pledge was created

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

1444762572
2015-10-13 18:56:12 UTC
2015-10-13T18:56:12+00:00

String,Integer

pledge_updated_at

No
Yes if action = update

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

If not specified it will be set to pledge_time.

This field is required if an update is being performed

campaign

No

event or category of transaction. Defaults to Partner Name

Gala, General, Mail Appeal

String

campaign_id

No

campaign identifier to minimize duplicates

String

parent_campaign

No

parent_campaign is only needed if you organize your campaigns in a hierarchy (for example, you organize your campaigns into categories). If parent_campaign is provided, it will be the parent of the provided campaign.

Events, Galas

String

parent_campaign_id

No

String

fund

No

larger group or fund of where the money ends up
https://support.kindful.com/hc/en-us/articles/217204108

General, Restricted, Africa

String

fund_id

No

fund identifier to minimize duplicates

String

acknowledged

No

used to determine if additional communication has occurred in addition to a transaction receipt email

Y,N,0,1,true,false

boolean

pledge_note

No

text details about pledge

occupation

No

Dentist

String

retired_or_not_employed

No

True/False or Yes/No

False

contact_with_non_cash_gift

import format for sending contact information in with non-cash gifts (in-kind)

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
  "data_format": "contact_with_non_cash_gift",
  "data_type": "json",
  "action_type": "create",
  "data":
  [{
    "id": "1",
    "first_name": "john",
    "last_name": "doe",
    "employer": "kindful",
    "email": "john@kindful.com",
    "alt_email": "john+1@kindful.com",
    "addr1": "1 main st",
    "addr2": "appt 2",
    "city": "nashville",
    "state": "TN",
    "postal": "37215",
    "country": "USA",
    "title": "Mr",
    "birthday": "2015/05/18",
    "primary_phone": "6152605555",
    "alt_phone": "6152606666",
    "fax_phone": "6152607777",
    "spouse_first": "Emi",
    "spouse_last": "Canahuati",
    "gender": "M",
    "created_at": "2015-10-13T18:56:12+00:00",
    "updated_at": "2015-10-13T18:56:12+00:00",
    "campaign": "Test Campaign",
    "campaign_id": "123",
    "fund": "Test Fund",
    "fund_id": "123",  
    "non_cash_gift_id": "1",
    "amount_in_cents": "5000",
    "non_cash_gift_time": "2015-10-13T18:56:12+00:00",
    "non_cash_gift_updated_at": "2015-10-13T18:56:12+00:00",
    "non_cash_gift_note": "yolo",
    "non_tax_deductible_amount_in_cents": "1000"
  }]
}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

data_format
string
action_type
string
data_type
string
 

The id field is specific to the API application you have created on your account. This used to keep duplicates out. The same contact record can be specified multiple times without causing duplicates.

If id is not provided then to remove duplicates we perform a record match by first_name + last_name + email or company_name + email. This is not ideal and poses a risk to your data, so please try to specify an identifier.

If non_cash_gift_id is not provided then we will generate a guid for it internally.

Asset Type

The default Asset Type set when passing in a non cash gift is "Other".

columns
required
notes
example
type

id

No

Contact ID

123ABC

String

first_name

Yes unless company_name is populated

last_name

Yes unless company_name is populated

String

company_name

Yes unless first and last name are populated

String

email

No

valid email address

String

alt_email

No

valid email address

String

addr1

No

String

addr2

No

String

city

No

String

state

No

state abbreviation TN,NY

String

postal

No

valid country postal code. 5 digits if United States

String

country

No

United States

http://www.worldatlas.com/aatlas/ctycodes.htm the full name from the list above. the A2 (ISO) code also can be used.

title

No

Example: Mr., Ms., Dr.

String

birthday

No

yyyy/mm/dd
mm/dd/yyyy
yyyy-mm-dd
mm-dd-yyyy

String

primary_phone

No

digits or with () - -

String

alt_phone

No

String

fax_phone

No

String

spouse_first

No

String

spouse_last

No

String

gender

No

Male = M, Female=F, Unknown=U. if blank the gender will be guessed based on name

M

M/F/U

created_at

No

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

updated_at

No
Yes if action = update and your updating contact

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

non_cash_gift_id

No

234DEF

amount_in_cents

Yes

5000 = $50

500

currency

No

uppercase

USD

non_cash_gift_time

Yes

when non cash gift was created

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

1444762572
2015-10-13 18:56:12 UTC
2015-10-13T18:56:12+00:00

String,Integer

non_cash_gift_updated_at

No
Yes if action = update

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

If not specified it will be set to pledge_time.

This field is required if an update is being performed

campaign

No

event or category of transaction. Defaults to Partner Name

https://support.kindful.com/hc/en-us/articles/217204108

Gala, General, Mail Appeal

String

campaign_id

No

campaign identifier to minimize duplicates

String

parent_campaign

No

parent_campaign is only needed if you organize your campaigns in a hierarchy (for example, you organize your campaigns into categories). If parent_campaign is provided, it will be the parent of the provided campaign.

Events, Galas

String

parent_campaign_id

No

String

fund

No

larger group or fund of where the money ends up

https://support.kindful.com/hc/en-us/articles/217204108

General, Restricted, Africa

String

fund_id

No

fund identifier to minimize duplicates

String

acknowledged

No

used to determine if additional communication has occurred in addition to a transaction receipt email

Y,N,0,1,true,false

boolean

non_cash_gift_note

No

text details about non cash gift

non_tax_deductible_amount_in_cents

occupation

No

Dentist

String

retired_or_not_employed

No

True/False or Yes/No

False

contact_with_soft_credit

import format for sending contact information in with soft credits

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
  "data_format": "contact_with_soft_credit",
  "data_type": "json",
  "action_type": "create",
  "data":
  [{
    "id": "1",
    "first_name": "john",
    "last_name": "doe",
    "employer": "kindful",
    "email": "john@kindful.com",
    "alt_email": "john+1@kindful.com",
    "addr1": "1 main st",
    "addr2": "appt 2",
    "city": "nashville",
    "state": "TN",
    "postal": "37215",
    "country": "USA",
    "title": "Mr",
    "birthday": "2015/05/18",
    "primary_phone": "6152605555",
    "alt_phone": "6152606666",
    "fax_phone": "6152607777",
    "spouse_first": "Emi",
    "spouse_last": "Canahuati",
    "gender": "M",
    "created_at": "2015-10-13T18:56:12+00:00",
    "updated_at": "2015-10-13T18:56:12+00:00",
    "campaign": "Test Campaign",
    "campaign_id": "123",
    "fund": "Test Fund",
    "fund_id": "123",  
    "soft_credit_id": "1",
    "amount_in_cents": "500",
    "currency": "USD",
    "soft_credit_time": "2015-10-13T18:56:12+00:00",
    "soft_credit_updated_at": "2015-10-13T18:56:12+00:00",
    "soft_credit_note": "yolo"
  }]
}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

data_format
string
action_type
string
data_type
string
 

The id field is specific to the API application you have created on your account. This used to keep duplicates out. The same contact record can be specified multiple times without causing duplicates.

If id is not provided then to remove duplicates we perform a record match by first_name + last_name + email or company_name + email. This is not ideal and poses a risk to your data, so please try to specify an identifier.

If soft_credit_id is not provided then we will generate a guid for it internally.

columns
required
notes
example
type

id

No

Contact ID

123ABC

String

first_name

Yes unless company_name is populated

last_name

Yes unless company_name is populated

String

company_name

Yes unless first and last name are populated

String

email

No

valid email address

String

alt_email

No

valid email address

String

addr1

No

String

addr2

No

String

city

No

String

state

No

state abbreviation TN,NY

String

postal

No

valid country postal code. 5 digits if United States

String

country

No

United States

http://www.worldatlas.com/aatlas/ctycodes.htm the full name from the list above. the A2 (ISO) code also can be used.

title

No

Example: Mr., Ms., Dr.

String

birthday

No

yyyy/mm/dd
mm/dd/yyyy
yyyy-mm-dd
mm-dd-yyyy

String

primary_phone

No

digits or with () - -

String

alt_phone

No

String

fax_phone

No

String

spouse_first

No

String

spouse_last

No

String

gender

No

Male = M, Female=F, Unknown=U. if blank the gender will be guessed based on name

M

M/F/U

updated_at

No
Yes if action = update

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

If not specified it will be set to pledge_time.

This field is required if an update is being performed

1444762572
2015-10-13 18:56:12 UTC
2015-10-13T18:56:12+00:00

String,Integer

created_at

no

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

If not specified it will be set to pledge_time.

This field is required if an update is being performed

1444762572
2015-10-13 18:56:12 UTC
2015-10-13T18:56:12+00:00

String,Integer

soft_credit_id

Yes

234DEF

amount_in_cents

Yes

5000 = $50

500

soft_credit_time

Yes

when non cash gift was created

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

1444762572
2015-10-13 18:56:12 UTC
2015-10-13T18:56:12+00:00

String,Integer

soft_credit_updated_at

No
Yes if action = update

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

If not specified it will be set to pledge_time.

This field is required if an update is being performed

campaign

No

event or category of transaction. Defaults to Partner Name

https://support.kindful.com/hc/en-us/articles/217204108

Gala, General, Mail Appeal

String

campaign_id

No

campaign identifier to minimize duplicates

String

parent_campaign

No

parent_campaign is only needed if you organize your campaigns in a hierarchy (for example, you organize your campaigns into categories). If parent_campaign is provided, it will be the parent of the provided campaign.

Events, Galas

String

parent_campaign_id

No

String

fund

No

larger group or fund of where the money ends up

https://support.kindful.com/hc/en-us/articles/217204108

General, Restricted, Africa

String

fund_id

No

fund identifier to minimize duplicates

String

acknowledged

No

used to determine if additional communication has occurred in addition to a transaction receipt email

Y,N,0,1,true,false

boolean

soft_credit_note

No

text details about soft credit

Example:

{
  "data_format": "contact_with_soft_credit",
  "data_type": "json",
  "action_type": "create",
  "data":
  [{
    "id": "1",
    "first_name": "john",
    "last_name": "doe",
    "employer": "kindful",
    "email": "john@kindful.com",
    "alt_email": "john+1@kindful.com",
    "addr1": "1 main st",
    "addr2": "appt 2",
    "city": "nashville",
    "state": "TN",
    "postal": "37215",
    "country": "USA",
    "title": "Mr",
    "birthday": "2015/05/18",
    "primary_phone": "6152605555",
    "alt_phone": "6152606666",
    "fax_phone": "6152607777",
    "spouse_first": "Emi",
    "spouse_last": "Canahuati",
    "gender": "M",
    "created_at": "2015-10-13T18:56:12+00:00",
    "updated_at": "2015-10-13T18:56:12+00:00",
    "campaign": "Test Campaign",
    "campaign_id": "123",
    "fund": "Test Fund",
    "fund_id": "123",  
    "soft_credit_id": "1",
    "amount_in_cents": "500",
    "currency": "USD",
    "soft_credit_time": "2015-10-13T18:56:12+00:00",
    "soft_credit_updated_at": "2015-10-13T18:56:12+00:00",
    "soft_credit_note": "yolo"
  }]
}

contact_with_cause_team

Use this format to add a contact and transaction to a cause team in Kindful.

 
posthttps://app.kindful.com/admin/oauth2/api/v1/imports
{
"data_format": "contact_with_cause_team",
"action_type":"create",
"data_type":"json",
    "data": 
 [
    {
    "id":"123456",
    "title": "Mr.",
    "first_name": "John", // Not required if company_name is used
    "last_name": "Smith", // Not required if company_name is used
    "company_name": "Acme, Inc.", // Not required if first_name and last_name is used
    "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": "07/29/1985",
    "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",
    "campaign": "General",
    "campaign_id": "123abc",
    "fund": "General",
    "fund_id": "456def",
    "cause": "General",
    "cause_id": "12345",
		"team": "Team John",
	  "team_id": "12345", 
  	"team_member_first_name": "John", 
	  "team_member_last_name": "Smith", 
	  "team_member_id": "12345"
   } 
 ]

}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

data_format
string
action_type
string
data_type
string
 

The id field is an (API) application-specific field and is used to prevent duplicates when multiple applications are connected to the same Organization account.

For more information about creating and updating records, please see Intro to Record Matching

If id is not provided then:
To remove duplicates, we match based upon an exact match of first_name + last_name + email or company_name + email.
This is not ideal, so specify an identifier if at all possible.

If a transaction_id isn't provided then we will generate a guid for it, to be used internally.

columns
required
notes
example
type

id

No

Contact ID

123ABC

String

first_name

Yes unless company_name is populated

last_name

Yes unless company_name is populated

String

company_name

Yes unless first and last name are populated

Use company_name if the contact is not an individual but a company. First and last name can be blank in this case, if you specify First and Last Name, this will be the Primary Contact Name on the Organization Record.

String

employer

No

Company that individual works for

email

No

valid email address

String

alt_email

No

valid email address

String

addr1

No

String

addr2

No

String

city

No

String

state

No

state abbreviation TN,NY

String

postal

No

valid country postal code. 5 digits if United States

String

country

No

United States

http://www.worldatlas.com/aatlas/ctycodes.htm the full name from the list above. the A2 (ISO) code also can be used.

title

No

Mr, Ms, Dr

String

birthday

No

yyyy/mm/dd
mm/dd/yyyy
yyyy-mm-dd
mm-dd-yyyy

String

primary_phone

No

digits or with () - -

String

alt_phone

No

String

fax_phone

No

String

spouse_first

No

String

spouse_last

No

String

gender

No

Male = M, Female=F, Unknown=U. if blank the gender will be guessed based on name

M

M/F/U

created_at

No

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

updated_at

No
Yes if action = update and your updating contact

integer for unix timestamp (jan 1 1970) or string in UTC of ISO8601 or RFC3339 format

campaign

No

event or category of transaction. Defaults to Partner Name

https://support.kindful.com/hc/en-us/articles/217204108

Gala, General, Mail Appeal

String

campaign_id

No

campaign identifier to minimize duplicates

String

parent_campaign

No

parent_campaign is only needed if you organize your campaigns in a hierarchy (for example, you organize your campaigns into categories). If parent_campaign is provided, it will be the parent of the provided campaign.

Events, Galas

String

parent_campaign_id

No

String

fund

No

larger group or fund of where the money ends up
https://support.kindful.com/hc/en-us/articles/217204108

General, Restricted, Africa

String

fund_id

No

fund identifier to minimize duplicates

String

cause

No

General

String

cause_id

No

12345

String

team

No

General

String

team_id

No

12345

String

team_member_first_name

No

John

String

team_member_last_name

No

Smith

String

team_member_id

No

12345

String

occupation

No

Denist

String

retired_or_not_employed

No

True/False or Yes/No

False

Import Status by Job ID

get the status of a specific import job

 
gethttps://app.kindful.com/admin/oauth2/api/v1/imports/id
https://app.kindful.com/admin/oauth2/api/v1/imports/24dab09b-6166-4ab2-99ae-3dc3ca3763c1
A binary file was returned

You couldn't be authenticated

{
  "id":"24dab09b-6166-4ab2-99ae-3dc3ca3763c1",
  "status":"ready",
  "stats":{},
  "update_stats":{}
}
{
  "id": "ccfb226c-fb34-4be5-ac7c-452107d4f7b8",
  "status": "complete",
  "stats": 
   {"Fund": 1,
    "Campaign": 1,
    "Transaction": 1,
    "Integrations Fund Link": 1,
    "Integrations Campaign Link": 1},
  "update_stats": 
   {"Team": 0,
    "Cause": 0,
    "Contact": 0,
    "Team Member": 0,
    "Transaction": 0,
    "Custom Field": 0,
    "Recurring Donation": 0,
    "Custom Field Group": 0},
  "notifications": 
   {
    "page": 0,
    "count": 1,
    "results": 
     [
      {"code": "transaction_id_reused_with_split",
       "desc": "transaction can't have same external_id as split transaction 1",
       "id": 1,
       "status": "open",
       "object": 
        { 
          "id": 1,
          "external_id": "1",
          "sync_version": 1,
          "transaction_time": "Tue, 13 Oct 2015 18:56:12 UTC +00:00",
          "updated_at": "Tue, 13 Oct 2015 20:56:12 UTC +00:00",
          "amount_in_cents": 1000,
          "campaign_id": 2,
          "fund_id": 2,
          "designation": nil,
          "campaign": { 
            "id": 2,
            "external_id": nil,
            "sync_version": 1,
            "name": "Test Campaign",
            "description": nil,
            "short_name": "Test Campaign",
            "created_at": "Tue, 04 Apr 2017 21:46:26 UTC +00:00",
            "updated_at": "Tue, 04 Apr 2017 21:46:31 UTC +00:00",
            "fund_id": 2,
            "fund": {
              "id": 2,
              "external_id": "6",
              "sync_version": 1,
              "name": "Test Fund",
              "created_at": "Tue, 04 Apr 2017 21:46:26 UTC +00:00",
              "updated_at": "Tue, 04 Apr 2017 21:46:26 UTC +00:00",
              "record_type": "fund",
              "_links": {"self": ""}
             },
            "record_type": "campaign",
            "_links": {"self": ""}
          },
          "fund": {
            "id": 2,
            "external_id": "6",
            "sync_version": 1,
            "name": "Test Fund",
            "created_at": "Tue, 04 Apr 2017 21:46:26 UTC +00:00",
            "updated_at": "Tue, 04 Apr 2017 21:46:26 UTC +00:00",
            "record_type": "fund",
            "_links": {"self": ""}
          },
          "contact": {
            "id": 1,
            "external_id": "1",
            "sync_version": 1,
            "donor_type": "Person",
            "title": "Mr",
            "first_name": "pete",
            "last_name": "brumm",
            "gender": "M",
            "birthday": "2015/07/07",
            "company_name": nil,
            "employer": "kindful",
            "email": "pete@kindful.com",
            "primary_phone": "6155555555",
            "alt_phone": "6155556666",
            "fax_phone": "6155557777",
            "addr1": "1st Main st",
            "addr2": "Appt 1",
            "city": "Nashville",
            "state": "TN",
            "postal": "37215",
            "country": "United States",
            "spouse_first": "",
            "spouse_last": "",
            "created_at": "Tue, 13 Oct 2015 18:56:12 UTC +00:00",
            "updated_at": "Thu, 15 Oct 2015 18:56:12 UTC +00:00",
            "record_type": "contact",
            "_links": 
            {"self": "https://test.kindful.com/admin/contacts/1"}
          },
          "contact_id": 1,
          "acknowledged": false,
          "note": "this is a note",
          "transaction_type": "check",
          "was_refunded": false,
          "currency": "CAD",
          "check_num": "1234",
          "card_type": nil,
          "non_tax_deduct_amount_in_cents": 100,
          "is_donation": true,
          "custom_field_name1": nil,
          "custom_field_value1": nil,
          "custom_field_name2": nil,
          "custom_field_value2": nil,
          "custom_field_name3": nil,
          "custom_field_value3": nil,
          "deleted_at": nil,
          "record_type": "transaction",
          "_links": {
            "self": "",
            "contact": "https://test.kindful.com/admin/contacts/1"
          }
        }
      }
    ]
  }
}

Path Params

id
int32
required

required

 

Import Statuses

  • Started (UI Only) - If you create a new import in the UI and do not submit
    • Consolidated - When a consolidation worker is used to combine imports into one import
    • Removed - Legacy status (from v1 of Kindful)
    • Mapped (UI Only) - If you create a new import in the UI, this status will show when fields have been mapped
    • Ready - When we receive job from import API, this is the initial status prior to running
    • Scheduled - A scheduled job that is queued up to import. Kindful imports are worked one by one.
    • Pending - A alterternative status for 'Scheduled' or 'Ready'
    • Working - Import job is running. There will only ever be one 'working' job per app, per org
    • Complete - Import job has completed
    • Load_failed - files failed to load due to wrong file type or data in the file. If there is any standard error during the import, it will be marked with this general error.
    • Failed - Import job TAR file not present
    • Setup_failed - Prior to mapping import if error occurs in import setup worker
    • Error - If you send in data that we cannot process - we will note more in the error response
    • 404 Page not Found - If you send in a request to missing/mistyped endpoint or contain no or wrong authorization

Sync Status

get the summary statistics of imports which can be used to determine if it's a good time to sync

 
gethttps://app.kindful.com/admin/oauth2/api/v1/imports/stats
curl --request GET \
  --url https://app.kindful.com/admin/oauth2/api/v1/imports/stats
var request = require("request");

var options = { method: 'GET',
  url: 'https://app.kindful.com/admin/oauth2/api/v1/imports/stats' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://app.kindful.com/admin/oauth2/api/v1/imports/stats")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://app.kindful.com/admin/oauth2/api/v1/imports/stats");

xhr.send(data);
import requests

url = "https://app.kindful.com/admin/oauth2/api/v1/imports/stats"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "sync_enabled": false,
  "message": "There are prior jobs queued up.  Sync could not be started",
	"pending_jobs": 5,   // number of jobs (imports or links) that are queued up
  "pending_updates": 1 // number of record changes queued up

}
{
  "sync_enabled": true,
  "message": "ready",
  "pending_jobs": 0,
  "pending_updates": 0
}
 

Usage

If you are performing a two-way sync between your app and Kindful:

  1. Check this status API to determine if sync can be initiated: sync_enabled: true.
  2. Query for transactions/query "unlinked"
  3. Send in links to acknowledge the records using [transactions/link}(https://developer.kindful.com/docs
  4. Page through results and call link per page of results.
  5. If syncing hourly then delay and go to step 1. If sync_enabled: false then delay further until sync_enabled: true

This will ensure that prior linking jobs are complete. It also allows an admin to pause the sync while they work through any issues that they find.

Import Status in the UI

In the UI, you can view the status of an import in the Connected Accounts section of Settings (URL = .../admin/connected_accounts)

transactions/query

 
post/transactions/query
{
   "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]
   
}
{
  "query_token": "tok_abcd123"
}
{
   "query": [
     {
       "after": "2016/01/31",
       "or": ["changed", "not_linked"]
     }
   ],
   "per_page": 5,
   "columns": {
     "transaction": ["id", "external_id", "sync_version", "contact_id", "amount_in_cents", 
                     "transaction_time", "campaign", "fund", "updated_at"],
     "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]
   
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
	"page": 1,
  "has_more": true,
  "model": "transaction",
  "query_token": "tok_abcd123",
  "results": [
    {
      "id": 5000,
      "record_type": "transaction",
      "external_id": "app_specific_id",
      "sync_version": 2,
      "contact_id": 100000,
      "amount_in_cents": 500,
      "transaction_time": "2016-03-31 15:36:52 UTC",
      "updated_at": "2016-04-05 10:36:52 UTC",
      "batch_id": null,
      "fund": {
        "id": 1,
        "external_id": "app_spec_fund_id",
        "sync_version": 2,
        "name": "General"
      },
      "campaign": {
        "id": 2,
        "external_id": null,  // if not yet linked
        "sync_version": null,
        "name": "Golf"
      },
      "contact": {
       	"id": 100000,
        "record_type": "contact",
        "external_id": "app_specific_id_1",
        "sync_version": 5,
        "first_name": "Joe",
        "last_name": "Smith",
        "custom_fields": {
        	"Membership": { "custom_field_id": 1, "value": "Gold" },
          "Source": { "custom_field_id": 2, "value": ["web", "marketing"] }
        }
      },
      "_links": {
       	"self": "", // coming soon
        "contact": "https://org-sandbox.kindful.com/admin/contacts/1234"
      }
    }
  ],
  "_links": {
    "next": { "href": "/api/v1/contacts/query?request_token=tok_abcd123" }
  }

}
{
  "query_token": "tok_123",
  "errors": [
   	"query 'example' does not exist" 
  ]
}
{
	"page": 1,
  "has_more": true,
  "model": "contact",
  "query_token": "tok_abcd123",
  "warning": "Results could not be gathered in time.  Delay and try query with request_token again",
  "estimated_results_delay": 5, // 5 seconds delay is needed
  "results": [],
  "_links": {
    "next": { "href": "/api/v1/contacts/query?request_token=tok_abcd123" }
  }

}
{
    "type": "person.transaction.create",
    "id": "a387e8d7c591a216fc",
    "created_at": 1509645791,
    "data": {
        "object": {
            "id": 5903,
            "amount_in_cents": 20000,
            "created_at": 1509645789,
            "updated_at": 1509645789,
            "sync_version": 1,
            "note": "",
            "check_num": null,
            "is_donation": true,
            "currency_code": "USD",
            "non_tax_deduct_amount_in_cents": 0,
            "recurring_donation_id": null,
            "recurring_donation": null,
            "success": false,
            "canceled": false,
            "voided": false,
            "refunded": false,
            "deleted_at": null,
            "transaction_type": {
                "code": "one_time_transaction",
                "title": "One Time Transaction"
            },
            "campaign": {
                "id": 8,
                "name": "hey bro",
                "short_name": "hey bro",
                "deleted_at": null,
                "ancestors": []
            },
            "designation": null,
            "person": {
                "id": 2018,
                "email": "daniel+decline@kindful.com",
                "first_name": "Kee",
                "last_name": "Sobby",
                "guid": "ff24e4a0-a225-0135-1db7-0242ac12000c",
                "phone": "6154160435",
                "organization_name": null,
                "deleted_at": null,
                "donor_type": "Person"
            },
            "pledge": null,
            "product": null,
            "splits": []
        }
    }
}

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

contact_custom_fields
array of strings

list of custom field ids to return. can be ['all', 'linked'] or a list of the ids

per_page
string

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 has_more 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 estimated_results_delay will be specified to help reduce the number of requests.

A Word about Query Types

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
desc
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 an Application 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 before 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"}

contacts/query

 
post/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"]
   }
}
{
  "query_token": "tok_abcd123"
}
{
"query": [
 "not_linked" 
]}
{
"query": [
{ "after": "2015/01/31", "or": ["not_linked"] }
],
"per_page": 500,
"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"]
}}
A binary file was returned

You couldn't be authenticated

{
	"page": 1,
  "has_more": true,
  "model": "contact",
  "query_token": "tok_abcd123",
  "results": [
    {
      "id": 100000,
      "record_type": "contact",
      "external_id": "app_specific_id_1",
      "sync_version": 5,
      "first_name": "Joe",
      "last_name": "Smith",
      "created_at": "2016-03-31 15:36:52 UTC",
      "custom_fields": {
      	"Membership": { "custom_field_id": 1, "value": "Gold" },
        "Source": { "custom_field_id": 2, "value": ["web", "marketing"] }
      }
    },
    {
      "id": 101000,
      "record_type": "contact",
      "external_id": "app_specific_id_2", 
      "sync_version": 3,
      "first_name": "Jane",
      "last_name": "Smith",
      "created_at": "2016-03-31 15:36:52 UTC",
      "custom_fields": {
      	"Membership": { "custom_field_id": 1, "value": "Platinum" },
        "Source": { "custom_field_id": 2, "value": ["web"] }
      }
    }
  ],
  "_links": {
    "next": { "href": "/api/v1/contacts/query?request_token=tok_abcd123" }
  }

}
{
  "query_token": "tok_123",
  "errors": [
   	"query 'example' does not exist" 
  ]
}

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 https://developer.kindful.com/v1.0/docs/groups-1 for info on how to retrieve all groups (and group IDs) in the account.

field_has_value (coming soon)

1

no limit

{"field_has_value": ["employer"]

Will return only contacts with the specified value.

custom_field_has_value (coming soon)

1

no limit

{"custom_field_has_value": ["Wealth Data"]}

Will return only contacts with the specified custom field value.

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.

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

contacts/email_exist

Use this API endpoint as a way to quickly check if a contact already exists in the Kindful database

 
gethttps://app.kindful.com/admin/oauth2/api/v1/contacts/email_exist
https://app.kindful.com/admin/oauth2/api/v1/contacts/email_exist?email=ace@email.com
A binary file was returned

You couldn't be authenticated

{
  "exist": true
}
<!DOCTYPE html>
<html>
    <head>
        <title>The page you were looking for doesn't exist (404)</title>
        <style type="text/css">
    body { background-color: #fff; color: #666; text-align: center; font-family: arial, sans-serif; }
    div.dialog {
      width: 100%;
      margin: 4em auto 0 auto;
    }
   img.kindful-logo{
      max-width: 400px;
    }
    h1 { margin-top: 30px; font-size: 1.75em; line-height: 1em; margin-bottom: 5px; }
    @media(max-width: 500px){
      img.kindful-logo{
        max-width: 250px;
      }
    }
  </style>
    </head>
    <body>
        <!-- This file lives in public/404.html -->
        <div class="dialog">
            <img class="kindful-logo" src="/assets/kindful-large-logo.png" />
            <h1>The page you were looking for doesn't exist.</h1>
            <p>You may have mistyped the address or the page may have moved.</p>
        </div>
    </body>
</html>
 

Use this endpoint to check if a contact already exists in the Kindful database. This is valuable if you are looking to append to a contact or add a note/transaction/pledge/etc to a contact ONLY if they already exist in the database.

details

Using the API to query Kindful for an Organization's details

 
gethttps://app.kindful.com/admin/oauth2/api/v1/details
https://app.kindful.com/admin/oauth2/api/v1/details
A binary file was returned

You couldn't be authenticated


{
 "name": "Organization Name",
 "email": "org@email.com",
 "subdomain": "org-subdomain",
 "root_url": "https://org-subdomain.kindful.com/",
 "time_zone": "Central Time (US & Canada)",
 "ein": "12-3456789",
 "city": "Nashville",
 "state": "TN",
 "country": "United States"
}
 

campaigns

get a list of campaigns and associated parameters from a Kindful account

 
gethttps://app.kindful.com/admin/oauth2/api/v1/campaigns
curl --request GET \
  --url https://app.kindful.com/admin/oauth2/api/v1/campaigns
var request = require("request");

var options = { method: 'GET',
  url: 'https://app.kindful.com/admin/oauth2/api/v1/campaigns' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://app.kindful.com/admin/oauth2/api/v1/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://app.kindful.com/admin/oauth2/api/v1/campaigns");

xhr.send(data);
import requests

url = "https://app.kindful.com/admin/oauth2/api/v1/campaigns"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
	{
    "id": 84880,
    "name": "General",
    "lft": 1,
    "raised": "138813",
    "goal": "0",
    "full_name": "General",
    "indented_name": "General",
    "url": "https://subdomain.kindful.com/campaigns/84880",
    "external_id": null
  	},
  	{
    "id": 84882,
    "name": "Blue Moon Pledges",
    "lft": 3,
    "raised": "3381",
    "goal": "0",
    "full_name": "Blue Moon Pledges",
    "indented_name": "Blue Moon Pledges",
    "url": "https://subdomain.kindful.com/campaigns/84882",
    "external_id": null
  	}
  ]

Query Params

chapter_id
string

The chapter id to receive the campaigns for. Null only pulls from primary organization

 

funds

 
gethttps://app.kindful.com/admin/oauth2/api/v1/funds
curl --request GET \
  --url https://app.kindful.com/admin/oauth2/api/v1/funds
var request = require("request");

var options = { method: 'GET',
  url: 'https://app.kindful.com/admin/oauth2/api/v1/funds' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://app.kindful.com/admin/oauth2/api/v1/funds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://app.kindful.com/admin/oauth2/api/v1/funds");

xhr.send(data);
import requests

url = "https://app.kindful.com/admin/oauth2/api/v1/funds"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
	{
    "id": 14263,
    "external_id": null,
    "sync_version": 1,
    "name": "Plants and Soil",
    "created_at": "2017-01-25T11:53:03-06:00",
    "updated_at": "2017-01-25T11:53:03-06:00",
    "record_type": "fund",
    "_links": {
      "self": ""
    }
  },
  {
    "id": 88360,
    "external_id": null,
    "sync_version": 1,
    "name": "Pest Control Services",
    "created_at": "2017-01-25T11:52:37-06:00",
    "updated_at": "2017-01-25T11:53:12-06:00",
    "record_type": "fund",
    "_links": {
      "self": ""
    }
  }
]
 

groups

 
gethttps://app.kindful.com/admin/oauth2/api/v1/groups
https://app.kindful.com/api/v1/groups
https://app-sandbox.kindful.com/api/v1/groups
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
  { 
   "id": "1", 
   "name": "Donors in Denver", 
   "member_count": "32" 
  },
  { 
   "id": "2", 
   "name": "2016 Volunteers", 
   "member_count": "1287" 
  }
]
 

custom_fields

list of custom fields that are available for the organization

 
gethttps://app.kindful.com/admin/oauth2/api/v1/custom_fields
https://app.kindful.com/api/v1/custom_fields
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
  { id: 1, name: "Membership Type", custom_field_group: {id: 9, name: "General"}, field_type: "select", field_values: ["Gold", "Silver"]},  
  { id: 2, name: "Children Names", custom_field_group: {id: 9, name: "General"}, field_type: "text", field_values: null},
  { id: 3, name: "Completed Classes", custom_field_group: {id: 9, name: "General"}, field_type: "multi_select", field_values: ["2015-Q1", "2015-Q2", "2015-Q3", "2015-Q4"]}, // multi selects can not contain commas as that is what they are split on.
  { id: 4, name: "Class Notes", custom_field_group: {id: 9, name: "General"}, field_type: "text_area", field_values: null},
  { id: 5, name: "Graduation Date", custom_field_group: {id: 9, name: "General"}, field_type: "date", field_values: null}  // date format is mm/dd/yyyy when passing in data.
]
{ status: 'error', message: 'No Custom Field Group matches that id.' }

Query Params

custom_field_group_id
string

The custom field group id to receive the custom fields for. Null only pulls from primary organization

 

integrations/status

Update Kindful on the status of the integration as a means to provide feedback to users on the Kindful side.

 
posthttps://app.kindful.com/admin/oauth2/api/v1/integrations/status
{
	"data": {
  	"status": "Connected", 
    "units": "5"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "allow_campaign_sync": true,
  "allow_remote_campaign_creation": false,
  "contact_name_format": "display_name",
  "enable_local_changes_push": false,
  "enable_remote_changes_pull": false,
  "id": 13,
  "name": null,
  "sync_enabled": false,
  "type": "Integrations::Application",
  "units": 5,
  "fetch_transactions_after": null,
  "push_transactions_after": null,
  "first_sync_at": null,
  "first_sync_completed_at": null,
  "last_synced_at": null,
  "last_sync_completed_at": null,
  "org_name": "Nonprofit Organization",
  "subdomain": "nonprofit",
  "org_trial_tier": false
}

Body Params

status
string
required

Must be one of the following values:

units
string

Use units to pass in the number of connected users to your application

 

You will need the data_query scope for this endpoint.

Units

Use units to send Kindful the number of connected accounts/users to your application.

custom_field_groups

list of custom field groups that are available for the organization

 
gethttps://app.kindful.com/admin/oauth2/api/v1/custom_field_groups
https://app.kindful.com/api/v1/custom_field_groups
A binary file was returned

Your OAuth2 token is incorrect or has expired

[
  {
    "id": 1794,
    "name": "Member Information"
  },
  {
    "id": 1791,
    "name": "Membership"
  },
  {
    "id": 1785,
    "name": "Information"
  },
  {
    "id": 1582,
    "name": "Services Team"
  },
 
]
 

verify_event

Allows you to verify an event sent through a webhook. Helps you verify that a webhook request originated from Kindful.

 
get/id
app.kindful.com/admin/oauth2/api/v1/webhooks/verify_event?id=8d1f7ffea6ea3e36b5
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "type": "person.transaction.update",
  "id": "8d1f7ffea6ea3e36b5",// This is the id in the example request.
  "created_at": 1459185643,
  "data": {
    "object": {
      "id": 17948512,
      "amount_in_cents": 50000,
      "created_at": 1459185643,
      "updated_at": 1459185643,
      "sync_version": 1,
      "note": "You changed this",
      "check_num": "",
      "is_donation": true,
      "currency_code": "USD",
      "non_tax_deduct_amount_in_cents": 0,
      "recurring_donation_id": null,
      "recurring_donation": null,
      "success": true,
      "canceled": false,
      "voided": false,
      "refunded": false,
      "deleted_at": null,
      "transaction_type": {
        "code": "check",
        "title": "Check"
      },
      "campaign": {
        "id": 84949,
        "name": "General",
        "short_name": "General",
        "deleted_at": null,
        "ancestors": [],
        "external_id": "General"
      },
      "designation": null,
      "person": {
        "email": "",
        "first_name": "Pete",
        "guid": "9defb494-c7aa-4b65-a5c8-9ac7ce4b71c0",
        "id": 5734397,
        "last_name": "Brumm5",
        "organization_name": null,
        "phone": null,
        "deleted_at": null,
        "donor_type": "Person",
        "address": "1st Main St",
        "address2": "Suite 1",
        "city": "Nashville", 
        "state": "Tennessee",
        "postal_code": "37205",
        "country": "United States",
        "spouse": "Spouse Full Name",
        "spouse_first_name": "First",
        "spouse_last_name": "Last",
        "external_id": "2"
      },
      "pledge": null,
      "product": null,
      "splits": [],
      "external_id": "4000",
      "authorization": null,
      "card_last_four": null,
      "card_type": null
    }
  }
}

Query Params

id
string

The Webhook Event ID to verify.

 

Public Cause Data

 
get/cause-slug.json
https://organization-subdomain.kindful.com/my-first-cause.json
A binary file was returned

Your OAuth2 token is incorrect or has expired

{"cause":
  {"name":"My First Cause",
   "slug":"my-first-cause",
   "goal_in_cents":200000,
   "total_raised_amount_in_cents":466700,
   "donate_url":"http://organization-subdomain.kindful.com/campaigns/1234?cause_id=1234",
   "teams":[
      {"name":"Dream Name",
       "url":"http://organization-subdomain.kindful.com/my-first-cause/dream-name",
       "donate_url":"http://organization-subdomain.kindful.com/campaigns/1234?team_donate_id=1234"
      }
   ]
  }
}
 

dataType: jsonp

You can include a callback param with a function name, if desired.

Public Cause Team Data

All public team data is accessible via our api.

 
get/cause-slug/team-slug.json
https://organization-subdomain.kindful.com/my-first-cause/dream-team.json
A binary file was returned

Your OAuth2 token is incorrect or has expired

{"team":
  {"name":"Dream Name",
   "cause":"My First Cause",
   "donate_url":"https://organization-subdomain.kindful.com/campaigns/1234?team_donate_id=1234",
   "total_raised_amount_in_cents":466700,
   "goal_amount_in_cents":200000,
   "days_remaining":218,
   "team_members":[
      {"name":"John Doe",
        "raised_amount_in_cents":"4667.00"
      }
    ],
   "donations":[
      {"name":"Sally May",
       "amount_in_cents":10000
      },
      {"name":"Jim Trim",
       "amount_in_cents":456700
      }
    ]
  }
}
 

dataType: jsonp

You can include a callback param with a function name, if desired.

Public Campaign Data

Will need the campaign's access token.

 
get/campaigns/your-campaign-access-code-here.json
curl --request GET \
  --url http://example.com/campaigns/your-campaign-access-code-here.json
var request = require("request");

var options = { method: 'GET',
  url: 'http://example.com/campaigns/your-campaign-access-code-here.json' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://example.com/campaigns/your-campaign-access-code-here.json")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://example.com/campaigns/your-campaign-access-code-here.json");

xhr.send(data);
import requests

url = "http://example.com/campaigns/your-campaign-access-code-here.json"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{"campaign":
	{"name":"General",
	 "total_raised_amount_in_cents":13093328,
   "goal_amount_in_cents":5000000
  }
}
 

There is a checkbox on the Admin Campaign Edit pages that allows organizations to turn on api access to the campaign's name, total_raised_amount_in_cents, and goal_amount_in_cents.