Skip to content
Karani Docs

API reference

Base URL: https://karani.co/api/v1

Every request needs an api_key parameter.

Response shape

Section titled “Response shape”

Every response — success or error — has the same four keys:

{
  "success": true,
  "message": "",
  "type": "contacts.index",
  "data": []
}
Key Meaning
success Boolean
message Human-readable message; empty on success
type The operation, e.g. contacts.read
data The payload — an object or an array

Endpoints

Section titled “Endpoints”
Method Path Purpose
GET /contacts List all contacts
POST /contacts Create a contact
GET /contacts/{id} Read one contact
PUT /contacts/{id} Update a contact
GET /gifts List all gifts
POST /gifts Create a gift
GET /gifts/{id} Read one gift
PUT /gifts/{id} Update a gift
GET /pledges List all pledges
POST /pledges Create a pledge
GET /pledges/{id} Read one pledge
PUT /pledges/{id} Update a pledge
GET /tasks List all tasks
POST /tasks Create a task
GET /tasks/{id} Read one task
PUT /tasks/{id} Update a task
GET /giving-summary Look up a giving summary

Contacts

Section titled “Contacts”

List

Section titled “List”
Terminal window
curl "https://karani.co/api/v1/contacts?api_key=YOUR_KEY"

Each contact comes back with its related records loaded: tags, profilePicture, familyMembers, addresses, phones, and emails.

Internal fields — account_id, contact_org_id, contact_is_org, and the timestamps — are stripped from the response.

Read

Section titled “Read”
Terminal window
curl "https://karani.co/api/v1/contacts/123?api_key=YOUR_KEY"

Returns 404 if the contact doesn’t exist or isn’t in your account.

Create

Section titled “Create”
Terminal window
curl -X POST "https://karani.co/api/v1/contacts?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_fname": "Jane",
    "contact_lname": "Smith",
    "contact_status": "prospect"
  }'

Required:

  • contact_lname — unless contact_anonymous is 1
  • contact_status — contact, donor, prospect, archive, or lapsed_donor

Any other writable contact field can be included. Fields Karani doesn’t recognise are ignored rather than causing an error.

Creating a contact fires the contacts.create webhook.

Update

Section titled “Update”
Terminal window
curl -X PUT "https://karani.co/api/v1/contacts/123?api_key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_status": "donor"}'

Only the fields you send are changed. Fires contacts.update.

Gifts

Section titled “Gifts”

GET /gifts returns gifts newest-first by gift date, with the related contact and giftType loaded.

Creating and updating gifts follows the same pattern as contacts, and fires gifts.create and gifts.update.

Pledges

Section titled “Pledges”

Same pattern. Fires pledges.create and pledges.update.

Remember that pledge amounts are per gift, not annual, and that the start date determines how the pledge is counted — see Adding a pledge.

Tasks

Section titled “Tasks”

Same pattern. Fires tasks.create and tasks.update.

Giving summary

Section titled “Giving summary”
Terminal window
curl "https://karani.co/api/v1/giving-summary?api_key=YOUR_KEY"

A summary lookup of giving. Useful for displaying a total on your own site without pulling every gift.

Field names

Section titled “Field names”

The API uses Karani’s internal field names — contact_fname, contact_lname, gift_amount, pledge_frequency. The CSV field reference maps most of them to their human-readable labels.

The most reliable way to learn the exact shape of a record is to GET one and look at it.