Keela
API docs by Redocly

Keela API Reference (1.0.0)

Introduction

This API documentation outlines the endpoints provided by Keela, facilitating seamless integration with our platform.

Authentication and Authorization

To connect to our APIs and initiate the "user consent" procedure, configure authorization using the OAuth 2.0 protocol RFC 6749. Creating authorization requests

  • Contact support to create an app.
  • Get your client_id, client_secret and scope.
  • Get Base URL for your app.
  • Use the information to create authorization requests.
    Field Description Required
    client_id Identifies the app making the request. Yes
    scope Lists the scopes your app uses (e.g., "fundraising"). Yes
    redirect_uri Redirects users to this URL upon authorization. Yes
    response_type Set to "code" for the Keela OAuth Server. Yes
    state Defines the state between your request and the Keela OAuth Server response. Yes
    Managing flow
  • Your app sends an authorization request to the Keela OAuth 2.0 Server whenever a user connects to it.
  • After being forwarded to an authorization page, the user can grant your app access to their data. The process is now at the "user consent" stage.
  • The Keela OAuth 2.0 Server will return an authorization code (the "redirect_url") to your app if the user grants permission for it. Getting access and refresh tokens
  • Your app exchanges the authorization code for access and refresh tokens by sending it back to the Keela OAuth 2.0 Server. Making API calls
  • Call particular APIs with access tokens to interact with users' Keela organization data.
  • Use a refresh token to "refresh" an access token when it has run out.
  • Users must go through the authorization route again if a refresh token expires.
  • The refresh token expires in 101 days

Methods and parameters

HTTP methods

  • GET: Retrieve data without updates.
  • POST: Create new resources.
  • PUT: Update existing resources. Query String Parameters GET requests that fetch a list of data accept optional parameters (skip and limit) for pagination. The default values are 0 and 100, respectively.

    By requesting manageable chunks of data, you can limit response results and make them easier to work with by paginating your API requests. We paginate using offset and count in the URL query string because it gives you more control over how you view your data.

API Reference

Field types

  • string
  • boolean
  • timestamp - Note: This field needs to be one of the accepted formats. Refer to this link for more info about accepted formats
  • number

    Array Fields: Multiple values can either be passed using separator(;) or could be an array of values. Example: If there are 2 tags Tag 1 and Tag 2, you can use either of the following syntax: “Tags_name”: “Tag 1;Tag 2” or “Tags_name”: [ “Tag 1”, “Tag 2” ]

Error Codes

Code Error Description
400, 401 Invalid request Can be one of the following:
  • The grant_type is not supported.
  • The grant_type is not supported.
  • One or more request parameters are invalid.
401, 409 Unauthorized Can be one of the following:
  • This client is not authorized to use this service.
  • The organization has either been cancelled or blocked.
403 Permission denied You do not have the permission for this request.
404 Invalid Url This route does not exist.
415 Unsupported response type The response type is not supported by the authorization server.
500 Server error Internal server error.

Campaigns

Get Campaigns

Retrieves a list of campaigns

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Contacts

Get Contacts

Retrieves a list of contacts

query Parameters
_subCollection
string
Enum: "CompanyContacts" "PersonContacts"

Type of contact

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create Contact

Creates Contact based on the supplied parameters

Request Body schema: application/json
required
primaryEmail
required
string

Primary Email Address of the contact

firstName
string

First Name

lastName
string

Last Name

priority
string
Default: null
Enum: "Low" "Medium" "med" "High" null
isSolicitation
string
Default: "Unspecified"
Enum: "Yes" "y" "true" 1 "No" "n" false 0 "Unspecified" "unknown" "n/a"
subscriptionStatus
string
Default: "Unknown"
Enum: "Opted-In" "subscribed" "Opted-Out" "unsubscribed" "Unknown" "n/a"

Email Subscription Status

primaryPhone
string

Phone number of the contact

birthDate
string (Timestamp)

Refer to this link for more info about accepted formats

primaryAddress_street
string

Address Line 1

primaryAddress_unit
string

Address Line 2

primaryAddress_city
string

City

primaryAddress_postal
string

Postal Code/ Zip Code,

primaryAddress_region
string

State/ Region

primaryAddress_country
string

Country

CompanyContacts_id
string

Id of the company contact associated to the contact. The company must exist in Keela

CompanyContacts_name
string

Name of the company contact associated to the contact. If a company with same name exists, the contact will be linked to that company, else a new company will be created

Households_id
string

Id of the Household associated to the contact. The Household must exist in Keela

Households_name
string

Name of the Household associated to the contact. If a Household with same name exists, the contact will be linked to that household, else a new household will be created

Tags_id
string

Id of the Tag associated to the contact. The Tag must exist in Keela

Tags_name
string

Name of the Tag associated to the contact. If a Tag with same name exists, the contact will be linked to that Tag, else a new Tag will be created

website
string
twitter
string
facebook
string
youtube
string
linkedin
string
instagram
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "_id": "6Az6kZ8RHFKgAeM7y",
  • "primaryEmail": "[email protected]",
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "priority": "Low",
  • "isSolicitation": "No",
  • "subscriptionStatus": "Opted In",
  • "primaryPhone": "12345678",
  • "birthDate": {
    },
  • "primaryAddress": {
    },
  • "CompanyContacts": [
    ],
  • "Households": {
    },
  • "Tags": [
    ],
  • "website": "https://keela.com",
  • "facebook": "https://facebook.com/keela",
  • "twitter": "https://twitter.com/keela",
  • "youtube": "https://youtube.com/keela",
  • "linkedin": "https://linkedin.com/keela",
  • "instagram": "https://instagram.com/keela"
}

Create or update Contact

Creates or updates Contact based on the supplied parameters

Request Body schema: application/json
required
primaryEmail
required
string

Primary Email Address of the contact

firstName
string

First Name

lastName
string

Last Name

priority
string
Default: null
Enum: "Low" "Medium" "med" "High" null
isSolicitation
string
Default: "Unspecified"
Enum: "Yes" "y" "true" 1 "No" "n" false 0 "Unspecified" "unknown" "n/a"
subscriptionStatus
string
Default: "Unknown"
Enum: "Opted-In" "subscribed" "Opted-Out" "unsubscribed" "Unknown" "n/a"

Email Subscription Status

primaryPhone
string

Phone number of the contact

birthDate
string (Timestamp)

Refer to this link for more info about accepted formats

primaryAddress_street
string

Address Line 1

primaryAddress_unit
string

Address Line 2

primaryAddress_city
string

City

primaryAddress_postal
string

Postal Code/ Zip Code,

primaryAddress_region
string

State/ Region

primaryAddress_country
string

Country

CompanyContacts_id
string

Id of the company contact associated to the contact. The company must exist in Keela

CompanyContacts_name
string

Name of the company contact associated to the contact. If a company with same name exists, the contact will be linked to that company, else a new company will be created

Households_id
string

Id of the Household associated to the contact. The Household must exist in Keela

Households_name
string

Name of the Household associated to the contact. If a Household with same name exists, the contact will be linked to that household, else a new household will be created

Tags_id
string

Id of the Tag associated to the contact. The Tag must exist in Keela

Tags_name
string

Name of the Tag associated to the contact. If a Tag with same name exists, the contact will be linked to that Tag, else a new Tag will be created

website
string
twitter
string
facebook
string
youtube
string
linkedin
string
instagram
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "_id": "6Az6kZ8RHFKgAeM7y",
  • "primaryEmail": "[email protected]",
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "priority": "Low",
  • "isSolicitation": "No",
  • "subscriptionStatus": "Opted In",
  • "primaryPhone": "12345678",
  • "birthDate": {
    },
  • "primaryAddress": {
    },
  • "CompanyContacts": [
    ],
  • "Households": {
    },
  • "Tags": [
    ],
  • "website": "https://keela.com",
  • "facebook": "https://facebook.com/keela",
  • "twitter": "https://twitter.com/keela",
  • "youtube": "https://youtube.com/keela",
  • "linkedin": "https://linkedin.com/keela",
  • "instagram": "https://instagram.com/keela"
}

Households

Get Households

Retrieves a list of Households

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Impact Areas

Get Impact Areas

Retrieves a list of Impact Areas

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Sources

Get Sources

Retrieves a list of Sources

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Tags

Get Tags

Retrieves a list of Tags

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Transactions

Create Donation

Creates donation based on the supplied parameters

Request Body schema: application/json
required
amount
required
number

Total amount of the gift

paidAt
required
string

The date at which donation was made. Refer to this link for a list of accepted formats.

Contacts_name
string

The full Name of the contact

Contacts_primaryEmail
required
string

Primary email address of the contact

Campaigns_id
string

Id of the Campaign associated to the donation. The Campaign must exist in Keela

Campaigns_name
string

Name of the Campaign associated to the donation. If a Campaign with same name exists, the donation will be linked to it, else a new Campaign will be created

ImpactAreas_id
string

Id of the Impact Area associated to the donation. The Impact Area must exist in Keela

ImpactAreas_name
string

Name of the Impact Area associated to the donation. If a Impact Area with same name exists, the donation will be linked it, else a new Impact Area will be created

SoftCredits_id
string

Id of the Soft Credit associated to the donation. The Soft Credit must exist in Keela

SoftCredits_name
string

Name of the Soft Credit associated to the donation. If a Soft Credit with same name exists, the donation will be linked to it, else a new Soft Credit will be created

SoftCredits_splitAmount
string

Amount of Soft Credits. The amount is applied on array index. For Example: If SoftCredits_name is John;Cinderella and SoftCredits_amount is 100;200, John will have amount 100 and Cinderella will have amount 200

Sources_id
string

Id of the Source associated to the donation. The Source must exist in Keela

Sources_name
string

Name of the Source associated to the donation. If a Source with same name exists, the donation will be linked to it, else a new Source will be created

dedication
string
notes
string
paymentMethod
required
string
Default: "online"
Enum: "cash" "check/cheque" "online" "credit card" "externally via stripe" "externally via paypal" "externally via keelapay" "bank transfer" "other"

Payment Medium of the donation. Must be one of the offline payment methods

replacementLogic
string
Default: "only update empty fields"
Enum: "always replace" "only update empty fields" "always create a new contact"

Logic to use when merging with duplicates. Refer this link for more info

Responses

Request samples

Content type
application/json
{
  • "amount": 1000,
  • "paidAt": "2022-11-15",
  • "Contacts_name": "John Doe",
  • "Contacts_primaryEmail": "[email protected]",
  • "Campaigns_name": "Campaign 1",
  • "ImpactAreas_name": "Impact Area 1",
  • "SoftCredits_name": [
    ],
  • "SoftCredits_splitAmount": [
    ],
  • "Sources_name": "Source 1",
  • "dedication": "Dedicated to the cause",
  • "notes": "Test Notes",
  • "paymentMethod": "Cash",
  • "replacementLogic": "append"
}

Response samples

Content type
application/json
{
  • "_id": "hXrioSYHFqzGp8mYd",
  • "amount": 1000,
  • "paidAt": "2022-11-15T03:11:00.000Z",
  • "Contacts": {
    },
  • "Campaigns": {
    },
  • "ImpactAreas": {
    },
  • "SoftCredits": [
    ],
  • "Sources": {
    },
  • "dedication": "Dedicated to the cause",
  • "notes": "Test Notes",
  • "paymentMethod": "Cash",
  • "type": "Money",
  • "email": "[email protected]"
}

Create Revenue

Creates revenue based on the supplied parameters

Request Body schema: application/json
required
amount
required
number

Total amount of the gift

paidAt
required
string

The date at which donation was made. Refer to this link for a list of accepted formats.

Contacts_name
string

The full Name of the contact

Contacts_primaryEmail
required
string

Primary email address of the contact

Campaigns_id
string

Id of the Campaign associated to the donation. The Campaign must exist in Keela

Campaigns_name
string

Name of the Campaign associated to the donation. If a Campaign with same name exists, the donation will be linked to it, else a new Campaign will be created

ImpactAreas_id
string

Id of the Impact Area associated to the donation. The Impact Area must exist in Keela

ImpactAreas_name
string

Name of the Impact Area associated to the donation. If a Impact Area with same name exists, the donation will be linked it, else a new Impact Area will be created

SoftCredits_id
string

Id of the Soft Credit associated to the donation. The Soft Credit must exist in Keela

SoftCredits_name
string

Name of the Soft Credit associated to the donation. If a Soft Credit with same name exists, the donation will be linked to it, else a new Soft Credit will be created

SoftCredits_splitAmount
string

Amount of Soft Credits. The amount is applied on array index. For Example: If SoftCredits_name is John;Cinderella and SoftCredits_amount is 100;200, John will have amount 100 and Cinderella will have amount 200

Sources_id
string

Id of the Source associated to the donation. The Source must exist in Keela

Sources_name
string

Name of the Source associated to the donation. If a Source with same name exists, the donation will be linked to it, else a new Source will be created

dedication
string
notes
string
paymentMethod
required
string
Default: "online"
Enum: "cash" "check/cheque" "online" "credit card" "externally via stripe" "externally via paypal" "externally via keelapay" "bank transfer" "other"

Payment Medium of the donation. Must be one of the offline payment methods

replacementLogic
string
Default: "only update empty fields"
Enum: "always replace" "only update empty fields" "always create a new contact"

Logic to use when merging with duplicates. Refer this link for more info

Responses

Request samples

Content type
application/json
{
  • "amount": 1000,
  • "paidAt": "2022-11-15",
  • "Contacts_name": "John Doe",
  • "Contacts_primaryEmail": "[email protected]",
  • "Campaigns_name": "Campaign 1",
  • "ImpactAreas_name": "Impact Area 1",
  • "SoftCredits_name": [
    ],
  • "SoftCredits_splitAmount": [
    ],
  • "Sources_name": "Source 1",
  • "dedication": "Dedicated to the cause",
  • "notes": "Test Notes",
  • "paymentMethod": "Cash",
  • "replacementLogic": "append"
}

Response samples

Content type
application/json
{
  • "_id": "hXrioSYHFqzGp8mYd",
  • "amount": 1000,
  • "paidAt": "2022-11-15T03:11:00.000Z",
  • "Contacts": {
    },
  • "Campaigns": {
    },
  • "ImpactAreas": {
    },
  • "SoftCredits": [
    ],
  • "Sources": {
    },
  • "dedication": "Dedicated to the cause",
  • "notes": "Test Notes",
  • "paymentMethod": "Cash",
  • "type": "Money",
  • "email": "[email protected]"
}