API reference

Check that the API is up

GET /v1/healthNo key needed

Responses

• 200 The API is serving requests.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "status": "ok",
  "version": "1.0.0",
  "time": "2026-10-05T14:30:00Z"
}

Get the current organization

GET /v1/organization

The organization that owns the API key or session. There is no way to read any other organization.

Responses

• 200 The organization.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d01",
  "name": "Maple Street Food Bank",
  "ein": "84-1234567",
  "timezone": "America/Denver",
  "fiscal_year_start_month": 7,
  "mailing_address": "1200 Maple Street\nDenver, CO 80202",
  "receipt_signature_name": "Rosa Diaz",
  "receipt_signature_title": "Executive director",
  "receipt_footer": "Questions about your gift? Call 303-555-0100.",
  "intangible_religious_benefits": false,
  "receipt_logo_url": null,
  "require_two_step": false,
  "created_at": "2026-01-15T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z"
}

Update the current organization

PATCH /v1/organization

Admin role or a write-scoped key. Changing fiscal_year_start_month changes every fiscal-year report; the change is audited. require_two_step can be changed only by a signed-in admin whose session has completed two-step sign-in (aal2): an API key of any scope, and an admin who has not set up an authenticator app, get 403 for it (ADR-017). Once on, every member's session must complete two-step sign-in before the API answers it. Emits organization.updated.

Request body (OrganizationUpdate)

{
  "name": "Maple Street Food Bank",
  "fiscal_year_start_month": 7
}

Responses

• 200 The updated organization.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d01",
  "name": "Maple Street Food Bank",
  "ein": "84-1234567",
  "timezone": "America/Denver",
  "fiscal_year_start_month": 7,
  "mailing_address": "1200 Maple Street\nDenver, CO 80202",
  "receipt_signature_name": "Rosa Diaz",
  "receipt_signature_title": "Executive director",
  "receipt_footer": "Questions about your gift? Call 303-555-0100.",
  "intangible_religious_benefits": false,
  "receipt_logo_url": null,
  "require_two_step": false,
  "created_at": "2026-01-15T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z"
}

List users

GET /v1/users

Sorted by full_name, then id. Deactivated users are included (deactivated_at set) so admins can reactivate them. A person who has not signed in yet carries their newest invitation's status and sent time in invitation (ADR-017).

Parameters

Responses

• 200 A page of users.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
      "email": "amara@maplestreetfoodbank.org",
      "full_name": "Amara Okafor",
      "role": "staff",
      "created_at": "2026-10-12T15:00:00Z",
      "updated_at": "2026-10-12T15:00:00Z",
      "deactivated_at": null,
      "deactivated_by": null,
      "invitation": {
        "status": "queued",
        "queued_at": "2026-10-12T15:00:00Z",
        "sent_at": null,
        "attempts": 0,
        "last_error": null,
        "sending_configured": true,
        "sign_in_url": "https://app.maplestreetfoodbank.org/sign-in"
      }
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
      "email": "dana@maplestreetfoodbank.org",
      "full_name": "Dana Whitfield",
      "role": "admin",
      "created_at": "2026-01-15T16:00:00Z",
      "updated_at": "2026-01-15T16:00:00Z",
      "deactivated_at": null,
      "deactivated_by": null,
      "invitation": null
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
      "email": "luis@maplestreetfoodbank.org",
      "full_name": "Luis Ortega",
      "role": "staff",
      "created_at": "2026-02-02T18:12:00Z",
      "updated_at": "2026-02-02T18:12:00Z",
      "deactivated_at": null,
      "deactivated_by": null,
      "invitation": null
    }
  ],
  "next_cursor": null
}

Get the caller

GET /v1/users/me

Who is calling (B1.1). A signed-in user gets their user record, with the role, and their organization; an API key gets its organization and scopes. Any credential may call it, a read-only one included.

Responses

• 200 The caller.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "kind": "session",
  "organization": {
    "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d01",
    "name": "Maple Street Food Bank",
    "ein": "84-1234567",
    "timezone": "America/Denver",
    "fiscal_year_start_month": 7,
    "mailing_address": "1200 Maple Street\nDenver, CO 80202",
    "receipt_signature_name": "Rosa Diaz",
    "receipt_signature_title": "Executive director",
    "receipt_footer": "Questions about your gift? Call 303-555-0100.",
    "intangible_religious_benefits": false,
    "receipt_logo_url": null,
    "require_two_step": false,
    "created_at": "2026-01-15T16:00:00Z",
    "updated_at": "2026-10-05T14:30:00Z"
  },
  "access": "admin",
  "user": {
    "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
    "email": "dana@maplestreetfoodbank.org",
    "full_name": "Dana Whitfield",
    "role": "admin",
    "created_at": "2026-01-15T16:00:00Z",
    "updated_at": "2026-01-15T16:00:00Z",
    "deactivated_at": null,
    "deactivated_by": null,
    "invitation": null
  },
  "api_key": null
}

Invite a user

POST /v1/users/invite

Admin only. Creates the user with the given role, waiting for the person to sign in, and queues their invitation (ADR-017); the response's invitation says it is queued. Once the request has committed, the invitation drain has the platform's invite-member function create the person's login, and Supabase emails them a link to this deployment's confirm page, naming this organization; GET /v1/users then shows how it went (invitation.status), and their first sign-in links them to this user. Without the function set up on this deployment (invitation.sending_configured: false) the invitation waits in the queue and nothing is emailed. Nothing else creates a login: the sign-in page never does. 409 when the address already belongs to a user here, or to an active member of another organization ("This person already uses Operation Charity with another organization. One sign-in can belong to only one organization for now."; the answer never says which). When the address has a pending invitation from another organization, nothing is sent and the invitation ends pending_elsewhere (again never saying which). 429, with Retry-After, beyond 10 invitations an hour for the organization, first sends, resends and refusals together. The invitation is audited. Emits user.created.

Request body (UserInvite)

{
  "email": "amara@maplestreetfoodbank.org",
  "full_name": "Amara Okafor",
  "role": "staff"
}

Responses

• 201 The invited user, with the invitation queued.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "email": "amara@maplestreetfoodbank.org",
  "full_name": "Amara Okafor",
  "role": "staff",
  "created_at": "2026-10-12T15:00:00Z",
  "updated_at": "2026-10-12T15:00:00Z",
  "deactivated_at": null,
  "deactivated_by": null,
  "invitation": {
    "status": "queued",
    "queued_at": "2026-10-12T15:00:00Z",
    "sent_at": null,
    "attempts": 0,
    "last_error": null,
    "sending_configured": true,
    "sign_in_url": "https://app.maplestreetfoodbank.org/sign-in"
  }
}

Get a user

GET /v1/users/{id}

Deactivated users are returned with deactivated_at set; a person who has not signed in yet, with their newest invitation in invitation.

Parameters

Responses

• 200 The user.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "email": "luis@maplestreetfoodbank.org",
  "full_name": "Luis Ortega",
  "role": "staff",
  "created_at": "2026-02-02T18:12:00Z",
  "updated_at": "2026-02-02T18:12:00Z",
  "deactivated_at": null,
  "deactivated_by": null,
  "invitation": null
}

Change a user's role

PATCH /v1/users/{id}

Admin only. The last admin cannot be demoted (409). Emits user.updated.

Parameters

Request body (UserRoleChange)

{
  "role": "admin"
}

Responses

• 200 The updated user.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "email": "luis@maplestreetfoodbank.org",
  "full_name": "Luis Ortega",
  "role": "admin",
  "created_at": "2026-02-02T18:12:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deactivated_at": null,
  "deactivated_by": null,
  "invitation": null
}

Deactivate a user

POST /v1/users/{id}/deactivate

Admin only. Sets deactivated_at (the row is kept, ADR-005): the user can no longer sign in or use the API. Their past activity stays in the audit log. 409 if the user is already deactivated or is the last active admin. Undo with POST /v1/users/{id}/reactivate. Emits user.updated.

Parameters

Responses

• 200 The deactivated user.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "email": "luis@maplestreetfoodbank.org",
  "full_name": "Luis Ortega",
  "role": "staff",
  "created_at": "2026-02-02T18:12:00Z",
  "updated_at": "2026-10-05T16:00:00Z",
  "deactivated_at": "2026-10-05T16:00:00Z",
  "deactivated_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "invitation": null
}

Reactivate a user

POST /v1/users/{id}/reactivate

Admin only. Clears deactivated_at and deactivated_by; the user keeps their previous role. 409 if the user is not deactivated. Emits user.updated.

Parameters

Responses

• 200 The reactivated user.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "email": "luis@maplestreetfoodbank.org",
  "full_name": "Luis Ortega",
  "role": "staff",
  "created_at": "2026-02-02T18:12:00Z",
  "updated_at": "2026-02-02T18:12:00Z",
  "deactivated_at": null,
  "deactivated_by": null,
  "invitation": null
}

Send an invitation again

POST /v1/users/{id}/resend-invitation

Admin only (a signed-in admin; API keys get 403). Queues a new invitation for a person who has not signed in yet, for example when the first one expired, failed or was never sent, or ended pending_elsewhere and that other invitation has since been accepted or withdrawn (ADR-017); their older queued invitations are superseded, since only the newest is ever sent. The drain sends it after the request commits, to the address on their user; the link in an earlier invitation email then stops working. 409 when they have already signed in or the user is deactivated. 429, with Retry-After, beyond 10 invitations an hour for the organization, first sends, resends and refusals together. Without the invite function set up on this deployment the invitation waits in the queue (invitation.sending_configured: false). Audited. Emits user.updated.

Parameters

Responses

• 202 The user, with the new invitation queued.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "email": "amara@maplestreetfoodbank.org",
  "full_name": "Amara Okafor",
  "role": "staff",
  "created_at": "2026-10-12T15:00:00Z",
  "updated_at": "2026-10-12T15:00:00Z",
  "deactivated_at": null,
  "deactivated_by": null,
  "invitation": {
    "status": "queued",
    "queued_at": "2026-10-14T09:30:00Z",
    "sent_at": null,
    "attempts": 0,
    "last_error": null,
    "sending_configured": true,
    "sign_in_url": "https://app.maplestreetfoodbank.org/sign-in"
  }
}

List contacts

GET /v1/contacts

Sorted by last_name, first_name (org_name for organizations), then id. Soft-deleted records are excluded unless include_deleted=true. With include=giving every contact on the page carries giving (ContactGiving, ADR-016), worked out for the contacts on this page only. Every contact carries its tags; tag keeps contacts with any of the given tags (ADR-018). saved_list_id keeps a saved list's members now and snapshot_id a snapshot's (ADR-020), and include=total adds how many the whole query holds. POST /v1/contacts/export gives the same list as a CSV file, with the same filters in its body. Unknown query parameters are a 400 (ADR-020).

Parameters

Responses

• 200 A page of contacts.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 The saved list can't be worked out now (ADR-020): a condition names a tag, fund, campaign or appeal deleted since, a custom field whose type no longer allows it, or the stored filter no longer passes the grammar; or the list is deleted. Type `https://docs.operationcharity.org/problems/saved-list-needs-fixing`, with a pointer and a message per condition in `errors`. Restore the record or edit the list. Nothing was changed.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.
• 503 Working out a list's giving conditions took longer than 10 seconds, the gift load and the money library included (ADR-020). Nothing was changed; try again, or narrow the list. Lists are built for organizations of up to 20,000 contacts and 100,000 gifts.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
      "kind": "organization",
      "first_name": null,
      "last_name": null,
      "org_name": "Cedar Ridge Community Foundation",
      "display_name": "Cedar Ridge Community Foundation",
      "email": "grants@cedarridgecf.org",
      "phone": null,
      "household_id": null,
      "address_line1": "200 Grant St",
      "address_line2": "Suite 400",
      "city": "Denver",
      "region": "CO",
      "postal_code": "80203",
      "country": "US",
      "employer": null,
      "do_not_contact": false,
      "email_opt_in": false,
      "sms_opt_in": false,
      "source": "manual",
      "source_ref": null,
      "consented": true,
      "custom_fields": {},
      "tags": [],
      "created_at": "2026-02-10T17:00:00Z",
      "updated_at": "2026-02-10T17:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "kind": "person",
      "first_name": "Aiko",
      "last_name": "Nakamura",
      "org_name": null,
      "display_name": "Aiko Nakamura",
      "email": "aiko.nakamura@example.com",
      "phone": "+1 303 555 0142",
      "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
      "address_line1": "1420 Spruce St",
      "address_line2": null,
      "city": "Denver",
      "region": "CO",
      "postal_code": "80205",
      "country": "US",
      "employer": "Front Range Dental",
      "do_not_contact": false,
      "email_opt_in": true,
      "sms_opt_in": false,
      "source": "form",
      "source_ref": "donation-form",
      "consented": true,
      "custom_fields": {
        "volunteer": true,
        "t_shirt_size": "M"
      },
      "tags": [
        {
          "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
          "name": "Volunteer",
          "color": "green"
        }
      ],
      "created_at": "2026-03-01T15:00:00Z",
      "updated_at": "2026-10-05T14:30:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": "eyJsYXN0X25hbWUiOiJOYWthbXVyYSIsImlkIjoiLi4uIn0"
}

Create a contact

POST /v1/contacts

Emits contact.created. Does not dedupe; use the importer or GET /v1/contacts?email= to find existing records first. Every defined key in custom_fields is checked against its custom field definition (ADR-018): a value of the wrong type is a 422 pointing at /custom_fields/<key>; keys with no definition are stored as sent. Tags are added afterwards (PATCH /v1/contacts/{id}/tags).

Request body (ContactCreate)

{
  "kind": "person",
  "first_name": "Aiko",
  "last_name": "Nakamura",
  "email": "aiko.nakamura@example.com",
  "phone": "+1 303 555 0142",
  "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "address_line1": "1420 Spruce St",
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "employer": "Front Range Dental",
  "source": "form",
  "source_ref": "donation-form",
  "consented": true,
  "custom_fields": {
    "volunteer": true,
    "t_shirt_size": "M"
  }
}

Responses

• 201 The new contact.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "kind": "person",
  "first_name": "Aiko",
  "last_name": "Nakamura",
  "org_name": null,
  "display_name": "Aiko Nakamura",
  "email": "aiko.nakamura@example.com",
  "phone": "+1 303 555 0142",
  "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "employer": "Front Range Dental",
  "do_not_contact": false,
  "email_opt_in": true,
  "sms_opt_in": false,
  "source": "form",
  "source_ref": "donation-form",
  "consented": true,
  "custom_fields": {
    "volunteer": true,
    "t_shirt_size": "M"
  },
  "tags": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
      "name": "Volunteer",
      "color": "green"
    }
  ],
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a contact

GET /v1/contacts/{id}

A soft-deleted contact is still returned, with deleted_at set, so undo screens can show it. Lists hide it. With include=giving the contact carries giving (ContactGiving, ADR-016); with include=email_consent, email_consent (EmailConsentState, F1); include=giving,email_consent both.

Parameters

Responses

• 200 The contact.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "kind": "person",
  "first_name": "Aiko",
  "last_name": "Nakamura",
  "org_name": null,
  "display_name": "Aiko Nakamura",
  "email": "aiko.nakamura@example.com",
  "phone": "+1 303 555 0142",
  "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "employer": "Front Range Dental",
  "do_not_contact": false,
  "email_opt_in": true,
  "sms_opt_in": false,
  "source": "form",
  "source_ref": "donation-form",
  "consented": true,
  "custom_fields": {
    "volunteer": true,
    "t_shirt_size": "M"
  },
  "tags": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
      "name": "Volunteer",
      "color": "green"
    }
  ],
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update a contact

PATCH /v1/contacts/{id}

Partial update; omitted fields are unchanged, null clears. custom_fields replaces the stored object, so send every key to keep; each defined key whose value it adds or changes is checked against its custom field definition (ADR-018, 422 pointing at /custom_fields/<key>), a value equal to the stored one passes as it is, and keys with no definition are stored as sent. Emits contact.updated.

Parameters

Request body (ContactUpdate)

{
  "email_opt_in": false,
  "custom_fields": {
    "volunteer": true,
    "t_shirt_size": "M"
  }
}

Responses

• 200 The updated contact.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "kind": "person",
  "first_name": "Aiko",
  "last_name": "Nakamura",
  "org_name": null,
  "display_name": "Aiko Nakamura",
  "email": "aiko.nakamura@example.com",
  "phone": "+1 303 555 0142",
  "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "employer": "Front Range Dental",
  "do_not_contact": false,
  "email_opt_in": true,
  "sms_opt_in": false,
  "source": "form",
  "source_ref": "donation-form",
  "consented": true,
  "custom_fields": {
    "volunteer": true,
    "t_shirt_size": "M"
  },
  "tags": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
      "name": "Volunteer",
      "color": "green"
    }
  ],
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a contact

DELETE /v1/contacts/{id}

Soft delete (ADR-005): sets deleted_at and hides the contact from lists; POST /v1/contacts/{id}/restore undoes it. Still refused (409) while the contact has gifts, receipts or soft credits, so reports stay intact; merge or keep the record instead. Also refused (409, ADR-013) while the contact has a recurring donation that has not ended, or while a donation form payment from the contact's email address is in progress (an open checkout), so an online payment never arrives for a deleted donor. Communications, tasks and relationships are soft-deleted with it and restored with it. Emits contact.deleted with the row (deleted_at set) so the web app can offer undo.

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted contact

POST /v1/contacts/{id}/restore

Clears deleted_at and deleted_by on the contact and on the communications and tasks deleted with it. A relationship deleted with it comes back only when its other contact is live; while the other contact is still deleted, the relationship takes that contact's deletion and comes back with it (ADR-018). Children deleted on their own earlier stay deleted. 409 if the contact is not deleted. Emits contact.updated.

Parameters

Responses

• 200 The restored contact, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "kind": "person",
  "first_name": "Aiko",
  "last_name": "Nakamura",
  "org_name": null,
  "display_name": "Aiko Nakamura",
  "email": "aiko.nakamura@example.com",
  "phone": "+1 303 555 0142",
  "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "employer": "Front Range Dental",
  "do_not_contact": false,
  "email_opt_in": true,
  "sms_opt_in": false,
  "source": "form",
  "source_ref": "donation-form",
  "consented": true,
  "custom_fields": {
    "volunteer": true,
    "t_shirt_size": "M"
  },
  "tags": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
      "name": "Volunteer",
      "color": "green"
    }
  ],
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a contact's timeline

GET /v1/contacts/{id}/timeline

Everything about one contact in one list (B1.1): the gifts they gave (with receipt_required and display names), adjustments to those gifts (each with the gift it adjusts), soft credits they received (each with the credited gift), receipts and year-end statements issued to them, communications and tasks. Each item is discriminated by kind. Sorted by occurred_at descending, then kind in the order gift, adjustment, soft_credit, receipt, communication, task, then id. Dated entries (gifts, adjustments, soft credits, open tasks with a due date) sort at the start of their day in the organization's timezone. Soft-deleted soft credits, communications and tasks are excluded unless include_deleted=true (admin only). A deleted contact still has a timeline, like GET by id. kind narrows the list to some kinds, for example kind=gift,adjustment for giving history.

Parameters

Responses

• 200 A page of the contact's timeline, newest first.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "kind": "task",
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d19",
      "occurred_at": "2026-10-06T06:00:00Z",
      "occurred_on": "2026-10-06",
      "task": {
        "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d19",
        "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
        "grant_id": null,
        "kind": "thank_you",
        "title": "Thank Aiko Nakamura for her $50.00 gift",
        "due_on": "2026-10-06",
        "status": "open",
        "assigned_to": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
        "generated": true,
        "snoozed_until": null,
        "completed_at": null,
        "created_at": "2026-10-04T22:15:00Z",
        "updated_at": "2026-10-04T22:15:00Z",
        "deleted_at": null,
        "deleted_by": null
      }
    },
    {
      "kind": "communication",
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d18",
      "occurred_at": "2026-10-05T15:00:00Z",
      "occurred_on": null,
      "communication": {
        "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d18",
        "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
        "channel": "email",
        "direction": "outbound",
        "subject": "Thank you for keeping the shelter warm",
        "body_text": "Aiko, your gift of $50.00 to the Winter Shelter Fund means two more nights of warm beds. Thank you.",
        "body_html": null,
        "message_id": "<thanks-6d13@maplestreetfoodbank.org>",
        "thread_id": null,
        "from_address": "luis@maplestreetfoodbank.org",
        "to_addresses": [
          "aiko.nakamura@example.com"
        ],
        "occurred_at": "2026-10-05T15:00:00Z",
        "source": "manual",
        "logged_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
        "inbound_email_id": null,
        "email_message_id": null,
        "attachment_count": null,
        "created_at": "2026-10-05T15:00:00Z",
        "updated_at": "2026-10-05T15:00:00Z",
        "deleted_at": null,
        "deleted_by": null
      }
    },
    {
      "kind": "adjustment",
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d14",
      "occurred_at": "2026-10-05T06:00:00Z",
      "occurred_on": "2026-10-05",
      "adjustment": {
        "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d14",
        "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
        "kind": "reallocate",
        "amount_cents": 5000,
        "from_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
        "to_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
        "effective_on": "2026-10-05",
        "reason": "Donor asked that the gift be unrestricted.",
        "exception_reason": null,
        "consent_reference": "Donor email of 2026-10-03, filed in the donor record",
        "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
        "created_at": "2026-10-05T14:30:00Z",
        "updated_at": "2026-10-05T14:30:00Z"
      },
      "gift": {
        "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
        "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
        "contact_name": "Aiko Nakamura",
        "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
        "fund_name": "Winter Shelter Fund",
        "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
        "campaign_name": "Winter 2026",
        "appeal_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
        "appeal_name": "September letter",
        "grant_id": null,
        "kind": "one_time",
        "status": "posted",
        "amount_cents": 5000,
        "fair_market_value_cents": 0,
        "fee_covered_cents": 0,
        "received_on": "2026-10-04",
        "contribution_date": "2026-10-04",
        "payment_method": "card",
        "external_ref": "pi_3Q8kLm2eZvKYlo2C1aBcDeFg",
        "in_kind_description": null,
        "property_description": null,
        "book_fair_value_cents": null,
        "valuation_method": null,
        "nonfinancial_category": null,
        "pledge_id": null,
        "tribute_type": null,
        "tribute_name": null,
        "notify_contact_id": null,
        "notes": "Gave through the website after the September letter.",
        "receipt_required": false,
        "donation_form_id": null,
        "donation_form_title": null,
        "recurring_donation_id": null,
        "recurring_interval": null,
        "batch_id": null,
        "batch_name": null,
        "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
        "created_at": "2026-10-04T22:15:00Z",
        "updated_at": "2026-10-04T22:15:00Z"
      }
    },
    {
      "kind": "receipt",
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d16",
      "occurred_at": "2026-10-04T22:20:00Z",
      "occurred_on": null,
      "receipt": {
        "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d16",
        "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
        "kind": "gift",
        "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
        "tax_year": null,
        "contribution_date": "2026-10-04",
        "total_cents": 5000,
        "deductible_cents": 5000,
        "goods_services_statement": "No goods or services were provided in exchange for this contribution.",
        "rendered_text": "Maple Street Food Bank\n1200 Maple Street\nDenver, CO 80202\nEIN 84-1234567\n\nContribution receipt\n\nReceipt number: 3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d16\nDate issued: October 4, 2026\n\nDonor\nAiko Nakamura\n\nContribution\nContribution date: October 4, 2026\nAmount: $50.00\nDesignated to: General fund (unrestricted)\nDeductible amount: $50.00\n\nNo goods or services were provided in exchange for this contribution.\n\nThis receipt is your written acknowledgment of this contribution for federal income tax purposes. Please keep it with your tax records.\n",
        "supersedes_receipt_id": null,
        "superseded_at": null,
        "reissue_reason": null,
        "sent_at": "2026-10-04T22:20:00Z",
        "sent_via": "email",
        "created_at": "2026-10-04T22:20:00Z",
        "updated_at": "2026-10-04T22:20:00Z"
      }
    },
    {
      "kind": "gift",
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "occurred_at": "2026-10-04T06:00:00Z",
      "occurred_on": "2026-10-04",
      "gift": {
        "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
        "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
        "contact_name": "Aiko Nakamura",
        "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
        "fund_name": "Winter Shelter Fund",
        "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
        "campaign_name": "Winter 2026",
        "appeal_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
        "appeal_name": "September letter",
        "grant_id": null,
        "kind": "one_time",
        "status": "posted",
        "amount_cents": 5000,
        "fair_market_value_cents": 0,
        "fee_covered_cents": 0,
        "received_on": "2026-10-04",
        "contribution_date": "2026-10-04",
        "payment_method": "card",
        "external_ref": "pi_3Q8kLm2eZvKYlo2C1aBcDeFg",
        "in_kind_description": null,
        "property_description": null,
        "book_fair_value_cents": null,
        "valuation_method": null,
        "nonfinancial_category": null,
        "pledge_id": null,
        "tribute_type": null,
        "tribute_name": null,
        "notify_contact_id": null,
        "notes": "Gave through the website after the September letter.",
        "receipt_required": false,
        "donation_form_id": null,
        "donation_form_title": null,
        "recurring_donation_id": null,
        "recurring_interval": null,
        "batch_id": null,
        "batch_name": null,
        "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
        "created_at": "2026-10-04T22:15:00Z",
        "updated_at": "2026-10-04T22:15:00Z"
      }
    }
  ],
  "next_cursor": null
}

Add or remove tags on a contact

PATCH /v1/contacts/{id}/tags

Staff and write keys (ADR-018). Adds the tags in add and takes off those in remove, in one change. Each id must be a live tag of the organization (422 with a pointer to the id). A tag that comes off is kept on record and the same assignment comes back when it is added again, so undoing a removal is adding the tag back. A deleted contact cannot be tagged (409; restore it first). When the contact's tags changed, its updated_at moves, the change is in the audit log with who made it, and contact.updated is emitted with the new tags; a request that changes nothing emits nothing. Answers the contact as GET does (without giving).

Parameters

Request body (ContactTagsUpdate)

{
  "add": [
    "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01"
  ]
}

Responses

• 200 The contact with its tags.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "kind": "person",
  "first_name": "Aiko",
  "last_name": "Nakamura",
  "org_name": null,
  "display_name": "Aiko Nakamura",
  "email": "aiko.nakamura@example.com",
  "phone": "+1 303 555 0142",
  "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "employer": "Front Range Dental",
  "do_not_contact": false,
  "email_opt_in": true,
  "sms_opt_in": false,
  "source": "form",
  "source_ref": "donation-form",
  "consented": true,
  "custom_fields": {
    "volunteer": true,
    "t_shirt_size": "M"
  },
  "tags": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
      "name": "Volunteer",
      "color": "green"
    }
  ],
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Tag, untag, delete or restore many contacts

POST /v1/contacts/bulkIdempotency-Key required

Staff and write keys (ADR-018). One action on up to 500 contacts: add_tag and remove_tag (with tag_id, a live tag), delete and restore. Not all-or-nothing: it answers 200 with each contact's outcome, in the order sent - changed, unchanged, or refused with the reason. Delete applies the rules of DELETE /v1/contacts/{id} to each contact (ADR-005: a contact with gifts, receipts or soft credits, a recurring donation that has not ended or a payment in progress is refused) and the others are deleted; restore those of POST /v1/contacts/{id}/restore. A deleted contact is refused for add_tag and remove_tag, and an id with no contact in this organization is refused for every action. A contact whose custom fields are still the text an old import stored is refused for every action, with the reason, until its custom fields are saved again (the database refuses any write to it). Undo is the opposite action on exactly the changed ids (remove_tag for add_tag and back, restore for delete). A delete stamps one time on every contact it deletes and on their communications, tasks and relationships, as a single delete would; a restore brings back each contact's own communications and tasks, and a relationship only once its other contact is live too (until then it waits for that contact's restore), exactly as POST /v1/contacts/{id}/restore does (ADR-018). Requires Idempotency-Key: a retry with the same key and body answers the first result and changes nothing more. Every change is written to the audit log per contact, with who made it, and emits that contact's own event as one at a time would: contact.updated for a tag added or removed and for a restore, contact.deleted for a delete. Unchanged and refused contacts emit nothing. 422 for more than 500 ids, a repeated id, a missing, deleted or unknown tag, or a tag_id with delete or restore.

Over a snapshot (ADR-020): send snapshot_id instead of contact_ids to start a bulk run that adds or removes a tag on the snapshot's members, or deletes them, exactly the frozen members (not a list its own changes move). The first call records the run with its action and tag; every later call sends the next_cursor it was given and follows the run's stored action and tag, never its body's. Each call takes the next 500 members by contact id, applies the rules above, records the contacts it changed with its time in one statement, and answers bulk_run_id and next_cursor (null once every member is taken: the run is completed); each call has its own Idempotency-Key. A cursor is taken only from whoever started the run, only while it is running (409 once it is being undone or undone), and lasts 24 hours; GET /v1/bulk-runs/{id} gives a fresh one. A delete run needs a signed-in admin on every call (403 for staff and API keys, who keep the delete of up to 500 hand-picked contacts); tagging runs take write access. A run's tag must still be live on every call: once it is deleted the run answers 409 until the tag is restored. A cursor naming no run of this organization is a 404. Each call takes the organization's evaluation lock and draws on its bucket (ADR-020, Cost): 429 with Retry-After while another evaluation holds the lock or the bucket is spent, so a run of more than 30 calls waits and continues. POST /v1/bulk-runs/{id}/undo reverses the run from its history.

Parameters

Request body (ContactBulkRequest)

{
  "action": "add_tag",
  "tag_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
  "contact_ids": [
    "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
    "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d81"
  ]
}

Responses

• 200 Each contact's outcome and the counts.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "action": "add_tag",
  "tag_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
  "results": [
    {
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "outcome": "unchanged",
      "reason": null
    },
    {
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d81",
      "outcome": "changed",
      "reason": null
    }
  ],
  "counts": {
    "changed": 1,
    "unchanged": 1,
    "refused": 0
  },
  "bulk_run_id": null,
  "next_cursor": null
}

Export contacts as CSV

POST /v1/contacts/export

Admins, staff and write-scoped keys (ADR-018); read-only members and read keys get 403. Takes up to 500 ids or the list's filters in its body and answers one CSV file with exactly the rows GET /v1/contacts gives this caller for the same filters (include_deleted admin only, as on the list), in the same order, unpaginated, and a column for each field it gives: Contact ID, Kind (Person or Organization), Name, First name, Last name, Organization name, Email, Phone, Household ID, Address line 1, Address line 2, City, State or province, Postal code, Country, Employer, Do not contact, Email opt-in, Opted out of appeals, Opted out of newsletters, Text opt-in, Source, Source reference, Consented (yes or no for each flag), Tags (their names, separated by "; "), Created at, Updated at, Deleted at, Deleted by (timestamps as the API writes them); then include=giving's summary (ADR-016), the same numbers: Lifetime giving (USD), Gifts, First gift date, Last gift date, Last gift ID, Last gift (USD), Last gift kind (One-time, Recurring, Pledge payment, In-kind or Grant payment), Largest gift (USD), empty where giving has null; then custom_fields: a column for every custom field in use, in their order and headed by the label, then one for each archived field or key with no definition that any row holds, headed by its label (archived) or its key; yes or no for true and false, JSON for anything else that is not text or a number. A header that would repeat one before it gets its key in brackets. Text cells (headers included) that start with =, +, -, @, a tab or a carriage return get a leading apostrophe, and so does each part of a cell after a semicolon or a tab (the list separator in some locales, where a spreadsheet splits lines there) or after a line break (where that spreadsheet also ends the row: a cell's own quotes keep a line break inside it there only when the cell starts the line) that starts with =, +, - or @, after any spaces or quotes; a cell holding a semicolon, a tab or a line break is quoted. So a spreadsheet does not run them as formulas (C5). One file holds at most 10,000 contacts and 4,000,000 bytes, whichever comes first, under the hosting's 4.5 MB response limit; past either it is a 422 of type https://docs.operationcharity.org/problems/export-too-large that says how many matched and how to narrow it (a tag, a kind, a search, fewer ids), and never a partial file. With saved_list_id or snapshot_id (ADR-020) it answers a saved list's or a snapshot's members from one evaluation, exactly the rows and columns GET /v1/contacts gives for the same parameters; a list that needs fixing is a 409, and a list with a giving condition draws on the organization's evaluation bucket (429) and answers within 10 seconds (503). The audit log then also keeps the list or snapshot and the filter as evaluated. One export also reads at most 32 MB of the contacts' stored custom fields (their JSON, keys included), with the same 422 past that. Rate-limited to 30 requests per minute per caller, in its own bucket. Every export is written to the audit log (action export, table_name contacts, row_id the export's id), because the file carries personal data: who (the user, or the API key's id), when, the ids of the contacts exported and how many ids were asked for (requested_count), or the filters, how many columns and which of the organization's custom-field keys they include, and how many rows. The record copies nobody's details: a search or an email filter is kept by its length only, and keys no field defines are counted, not named.

Request body (ContactExportRequest)

{
  "format": "csv",
  "ids": [
    "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
    "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d81"
  ]
}

Responses

• 200 The contacts.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 The saved list can't be worked out now (ADR-020): a condition names a tag, fund, campaign or appeal deleted since, a custom field whose type no longer allows it, or the stored filter no longer passes the grammar; or the list is deleted. Type `https://docs.operationcharity.org/problems/saved-list-needs-fixing`, with a pointer and a message per condition in `errors`. Restore the record or edit the list. Nothing was changed.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.
• 503 Working out a list's giving conditions took longer than 10 seconds, the gift load and the money library included (ADR-020). Nothing was changed; try again, or narrow the list. Lists are built for organizations of up to 20,000 contacts and 100,000 gifts.

"Contact ID,Kind,Name,First name,Last name,Organization name,Email,Phone,Household ID,Address line 1,Address line 2,City,State or province,Postal code,Country,Employer,Do not contact,Email opt-in,Opted out of appeals,Opted out of newsletters,Text opt-in,Source,Source reference,Consented,Tags,Created at,Updated at,Deleted at,Deleted by,Lifetime giving (USD),Gifts,First gift date,Last gift date,Last gift ID,Last gift (USD),Last gift kind,Largest gift (USD),T-shirt size,Volunteers with us\r\n3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05,Person,Aiko Nakamura,Aiko,Nakamura,,aiko.nakamura@example.com,'+1 303 555 0142,3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04,1420 Spruce St,,Denver,CO,80205,US,Front Range Dental,no,yes,no,no,no,form,donation-form,yes,Volunteer,2026-03-01T15:00:00+00:00,2026-10-05T14:30:00+00:00,,,75.00,2,2026-10-04,2026-11-04,3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d53,25.00,Recurring,50.00,M,yes\r\n"

Find contacts by a filter

POST /v1/contacts/search

Read access (ADR-020). The list builder's search: the contacts an unsaved filter (SavedListFilter) holds, as GET /v1/contacts gives them, a page at a time, sorted by last_name, first_name (org_name for organizations), then id. Stores nothing, as POST /v1/receipts/preview stores nothing. The filter is checked by the one grammar (422 with a pointer per problem, /filter/...); include=giving,total and include_deleted (admin only) are query parameters as on the list, and cursor pages with the same filter sent again. A filter with a giving condition loads the organization's gifts once and works them out in the money library, as the reports do: it draws on the organization's bucket of 30 such requests a minute (10 for one API key) and waits up to 5 seconds for the organization's other evaluations (429 with Retry-After past either), and answers within 10 seconds or 503.

Parameters

Request body (ContactSearchRequest)

{
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 1
          },
          "to": {
            "type": "year_end",
            "years_ago": 1
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 0
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  }
}

Responses

• 200 A page of the contacts the filter holds.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.
• 503 Working out a list's giving conditions took longer than 10 seconds, the gift load and the money library included (ADR-020). Nothing was changed; try again, or narrow the list. Lists are built for organizations of up to 20,000 contacts and 100,000 gifts.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "kind": "person",
      "first_name": "Aiko",
      "last_name": "Nakamura",
      "org_name": null,
      "display_name": "Aiko Nakamura",
      "email": "aiko.nakamura@example.com",
      "phone": "+1 303 555 0142",
      "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
      "address_line1": "1420 Spruce St",
      "address_line2": null,
      "city": "Denver",
      "region": "CO",
      "postal_code": "80205",
      "country": "US",
      "employer": "Front Range Dental",
      "do_not_contact": false,
      "email_opt_in": true,
      "sms_opt_in": false,
      "source": "form",
      "source_ref": "donation-form",
      "consented": true,
      "custom_fields": {
        "volunteer": true,
        "t_shirt_size": "M"
      },
      "tags": [
        {
          "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
          "name": "Volunteer",
          "color": "green"
        }
      ],
      "created_at": "2026-03-01T15:00:00Z",
      "updated_at": "2026-10-05T14:30:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null,
  "total": 1
}

Subscribe a contact to email updates

POST /v1/contacts/{id}/email-subscription

Rule C (ADR-024). A signed-in staff member or admin subscribes directly, recording how the person agreed (200). An API key always sends the confirmation email instead (202), at most 50 a day per key (429 for the 51st). Anyone who unsubscribed is only ever sent the confirmation (202), whoever asks. 409 for a do-not-contact contact or one with no usable address. Emits contact.updated when the contact changed.

Parameters

Request body (EmailSubscriptionRequest)

{
  "agreed_how": "in_person",
  "note": "Signed up at the spring open house"
}

Responses

• 200 Subscribed (or already was).
• 202 A confirmation email is on its way; nothing changes until the person confirms.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "outcome": "subscribed",
  "contact": {
    "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
    "kind": "person",
    "first_name": "Aiko",
    "last_name": "Nakamura",
    "org_name": null,
    "display_name": "Aiko Nakamura",
    "email": "aiko.nakamura@example.com",
    "phone": "+1 303 555 0142",
    "household_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
    "address_line1": "1420 Spruce St",
    "address_line2": null,
    "city": "Denver",
    "region": "CO",
    "postal_code": "80205",
    "country": "US",
    "employer": "Front Range Dental",
    "do_not_contact": false,
    "email_opt_in": true,
    "sms_opt_in": false,
    "source": "form",
    "source_ref": "donation-form",
    "consented": true,
    "custom_fields": {
      "volunteer": true,
      "t_shirt_size": "M"
    },
    "tags": [
      {
        "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
        "name": "Volunteer",
        "color": "green"
      }
    ],
    "created_at": "2026-03-01T15:00:00Z",
    "updated_at": "2026-10-05T14:30:00Z",
    "deleted_at": null,
    "deleted_by": null
  }
}

List consent events

GET /v1/email-consent-events

The append-only consent log (ADR-024). Read access. Sorted by seq, oldest first, then id. contact_id keeps one contact's events. Consent events emit nothing. Unknown query parameters are a 400.

Parameters

Responses

• 200 A page of events.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c8c01",
      "seq": 4182,
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "change": "subscribed",
      "topic": null,
      "source": "staff",
      "wording": "Subscribed by staff, who recorded how the person agreed",
      "box_ticked_by_default": null,
      "agreed_how": "in_person",
      "reason": "Signed up at the spring open house",
      "user_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
      "api_key_id": null,
      "import_job_id": null,
      "email_signup_id": null,
      "email_send_id": null,
      "reverses_seq": null,
      "backfilled": false,
      "stated_at": null,
      "recorded_at": "2026-10-13T15:00:00Z"
    }
  ],
  "next_cursor": null
}

List tags

GET /v1/tags

Read access. Sorted by name (case-insensitive), then id. Each tag says how many live contacts have it. Soft-deleted tags are excluded unless include_deleted=true (admin only).

Parameters

Responses

• 200 A page of tags.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02",
      "name": "Board",
      "color": "blue",
      "contact_count": 7,
      "created_at": "2026-09-01T16:00:00Z",
      "updated_at": "2026-10-06T09:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
      "name": "Volunteer",
      "color": "green",
      "contact_count": 23,
      "created_at": "2026-09-01T16:00:00Z",
      "updated_at": "2026-09-01T16:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create a tag

POST /v1/tags

Admin only (a signed-in admin; API keys get 403, ADR-006). The name is trimmed and must be unique among live tags whatever the case (409 otherwise); the color defaults to gray. Emits tag.created.

Request body (TagCreate)

{
  "name": "Volunteer",
  "color": "green"
}

Responses

• 201 The new tag.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
  "name": "Volunteer",
  "color": "green",
  "contact_count": 0,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a tag

GET /v1/tags/{id}

A soft-deleted tag is still returned, with deleted_at set, so undo screens can show it.

Parameters

Responses

• 200 The tag.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
  "name": "Volunteer",
  "color": "green",
  "contact_count": 23,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Rename or recolor a tag

PATCH /v1/tags/{id}

Admin only. Every contact with the tag shows the new name and color at once. 409 when another live tag has the name. Emits tag.updated.

Parameters

Request body (TagUpdate)

{
  "name": "Volunteers",
  "color": "teal"
}

Responses

• 200 The updated tag.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
  "name": "Volunteers",
  "color": "teal",
  "contact_count": 23,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a tag

DELETE /v1/tags/{id}

Admin only. Soft delete (ADR-005): the tag leaves every contact's tags and matches nobody in the tag filter, and its assignments are kept, so POST /v1/tags/{id}/restore puts it back on every contact it was on. Emits tag.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted tag

POST /v1/tags/{id}/restore

Admin only. Clears deleted_at and deleted_by; the tag is back on every contact that had it. 409 if the tag is not deleted, or if another live tag now has its name (rename one of them first). Emits tag.updated, as every restore does (ADR-005).

Parameters

Responses

• 200 The restored tag, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02",
  "name": "Board",
  "color": "blue",
  "contact_count": 7,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-10-06T09:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List custom fields

GET /v1/custom-field-definitions

Read access. Sorted by position, then id. Archived fields are excluded unless include_archived=true.

Parameters

Responses

• 200 A page of custom fields.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7b01",
      "key": "t_shirt_size",
      "label": "T-shirt size",
      "type": "choice",
      "choices": [
        "S",
        "M",
        "L",
        "XL"
      ],
      "position": 0,
      "value_count": 41,
      "mismatch_count": 2,
      "archived_at": null,
      "archived_by": null,
      "created_at": "2026-09-01T16:00:00Z",
      "updated_at": "2026-09-01T16:00:00Z"
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7b02",
      "key": "volunteer",
      "label": "Volunteers with us",
      "type": "yes_no",
      "choices": null,
      "position": 1,
      "value_count": 23,
      "mismatch_count": 0,
      "archived_at": null,
      "archived_by": null,
      "created_at": "2026-09-01T16:05:00Z",
      "updated_at": "2026-09-01T16:05:00Z"
    }
  ],
  "next_cursor": null
}

Define a custom field

POST /v1/custom-field-definitions

Admin only (a signed-in admin; API keys get 403, ADR-006). Defines what the contact page shows and edits under key. Values already saved under the key (an imported column) are kept as they are: the answer's value_count and mismatch_count say how many contacts hold one and how many of those do not fit, and GET /v1/custom-field-definitions/{id}/mismatches lists them, so nothing breaks until someone edits them. 409 when the organization has used the key before (archived fields keep theirs) or a field in use has the label. Unknown fields are a 422. Audited; emits custom_field_definition.created.

Request body (CustomFieldDefinitionCreate)

{
  "key": "t_shirt_size",
  "label": "T-shirt size",
  "type": "choice",
  "choices": [
    "S",
    "M",
    "L",
    "XL"
  ]
}

Responses

• 201 The new custom field.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7b01",
  "key": "t_shirt_size",
  "label": "T-shirt size",
  "type": "choice",
  "choices": [
    "S",
    "M",
    "L",
    "XL"
  ],
  "position": 0,
  "value_count": 41,
  "mismatch_count": 2,
  "archived_at": null,
  "archived_by": null,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z"
}

Get a custom field

GET /v1/custom-field-definitions/{id}

An archived field is returned too, with archived_at set.

Parameters

Responses

• 200 The custom field.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7b01",
  "key": "t_shirt_size",
  "label": "T-shirt size",
  "type": "choice",
  "choices": [
    "S",
    "M",
    "L",
    "XL"
  ],
  "position": 0,
  "value_count": 41,
  "mismatch_count": 2,
  "archived_at": null,
  "archived_by": null,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z"
}

Rename, reorder or retype a custom field

PATCH /v1/custom-field-definitions/{id}

Admin only. The label, the position and a choice field's choices change freely, except that a choice a live contact holds cannot be removed (409 naming it). The type changes only while no live contact holds a value (409 otherwise: archive the field and define a new one). The key never changes (422). 409 when a field in use has the label. Moving a field moves the ones in between, each audited and emitting custom_field_definition.updated, as the field itself does.

Parameters

Request body (CustomFieldDefinitionUpdate)

{
  "label": "Shirt size",
  "choices": [
    "XS",
    "S",
    "M",
    "L",
    "XL"
  ]
}

Responses

• 200 The updated custom field.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7b01",
  "key": "t_shirt_size",
  "label": "Shirt size",
  "type": "choice",
  "choices": [
    "XS",
    "S",
    "M",
    "L",
    "XL"
  ],
  "position": 0,
  "value_count": 41,
  "mismatch_count": 2,
  "archived_at": null,
  "archived_by": null,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z"
}

Archive a custom field

POST /v1/custom-field-definitions/{id}/archive

Admin only. Archiving is this resource's delete (ADR-005: nothing is removed): the field leaves the contact page's editing and the importer's suggestions, every saved value stays on its contacts and the key stays the organization's. Undo with POST /v1/custom-field-definitions/{id}/unarchive. 409 if it is already archived. Audited; emits custom_field_definition.deleted with archived_at set.

Parameters

Responses

• 200 The archived custom field.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7b03",
  "key": "newsletter_format",
  "label": "Newsletter format",
  "type": "text",
  "choices": null,
  "position": 2,
  "value_count": 12,
  "mismatch_count": 0,
  "archived_at": "2026-10-05T16:00:00Z",
  "archived_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-10-05T16:00:00Z"
}

Unarchive a custom field

POST /v1/custom-field-definitions/{id}/unarchive

Admin only. The field is back on the contact page in its old place. 409 if it is not archived, or if a field in use now has its label (rename one of them first). Audited; emits custom_field_definition.updated, as a restore does (ADR-005).

Parameters

Responses

• 200 The custom field, with `archived_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7b03",
  "key": "newsletter_format",
  "label": "Newsletter format",
  "type": "text",
  "choices": null,
  "position": 2,
  "value_count": 12,
  "mismatch_count": 0,
  "archived_at": null,
  "archived_by": null,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-10-06T09:00:00Z"
}

List the values that do not fit a custom field

GET /v1/custom-field-definitions/{id}/mismatches

Read access. The live contacts whose saved value under the field's key does not fit its type or choices (ADR-018): values imported before the field was defined, say. Nothing is refused because of them; editing the contact fixes each. Sorted by display_name (case-insensitive), then id. mismatch_count on the field is the total.

Parameters

Responses

• 200 A page of contacts and their values.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
      "display_name": "Ben Nakamura",
      "value": "Medium"
    },
    {
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d81",
      "display_name": "Priya Shah",
      "value": 2
    }
  ],
  "next_cursor": null
}

List saved lists

GET /v1/saved-lists

Read access. Sorted by name (case-insensitive), then id. Each list carries its problems (empty when it can be worked out). Soft-deleted lists are excluded unless include_deleted=true (admin only). Unknown query parameters are a 400.

Parameters

Responses

• 200 A page of saved lists.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
      "name": "Lapsed shelter donors",
      "description": "Gave to the shelter last fiscal year, not yet this year, and can be mailed.",
      "filter": {
        "version": 1,
        "match": "all",
        "conditions": [
          {
            "field": "gave",
            "period": {
              "basis": "fiscal",
              "from": {
                "type": "year_start",
                "years_ago": 1
              },
              "to": {
                "type": "year_end",
                "years_ago": 1
              }
            },
            "fund_ids": [
              "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
            ]
          },
          {
            "field": "gave",
            "period": {
              "basis": "fiscal",
              "from": {
                "type": "year_start",
                "years_ago": 0
              },
              "to": null
            },
            "not": true
          },
          {
            "field": "has_mailing_address"
          },
          {
            "field": "do_not_contact",
            "not": true
          },
          {
            "field": "tags",
            "match": "none",
            "tag_ids": [
              "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
            ]
          }
        ]
      },
      "version": 3,
      "problems": [],
      "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
      "created_at": "2026-10-01T16:00:00Z",
      "updated_at": "2026-10-05T14:30:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Save a list

POST /v1/saved-lists

Staff, admins and write keys (ADR-020). A list is a rule: its members are worked out whenever it is read, so "gave last fiscal year" rolls over by itself and a gift recorded a minute ago counts. The name is trimmed and unique among live lists whatever the case (409). The filter is checked whole by the one grammar (422 with a pointer per problem, /filter/...). version starts at 1. Lists belong to the organization: anyone with write access may edit or delete any list, and the audit log says who changed what. Emits saved_list.created.

Request body (SavedListCreate)

{
  "name": "Lapsed shelter donors",
  "description": "Gave to the shelter last fiscal year, not yet this year, and can be mailed.",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 1
          },
          "to": {
            "type": "year_end",
            "years_ago": 1
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 0
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  }
}

Responses

• 201 The saved list.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
  "name": "Lapsed shelter donors",
  "description": "Gave to the shelter last fiscal year, not yet this year, and can be mailed.",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 1
          },
          "to": {
            "type": "year_end",
            "years_ago": 1
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 0
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  },
  "version": 3,
  "problems": [],
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "created_at": "2026-10-01T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a saved list

GET /v1/saved-lists/{id}

Read access. A soft-deleted list is still returned, with deleted_at set, so undo screens can show it. include=count adds member_count, how many live contacts are on it now: one count(*) over the condition GET /v1/contacts?saved_list_id= pages, so the two agree for the same data. A count of a list with a giving condition draws on the organization's evaluation bucket (429) and answers within 10 seconds (503); a list with problems, or a deleted one, answers 409 for the count. Unknown query parameters are a 400.

Parameters

Responses

• 200 The saved list.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 The saved list can't be worked out now (ADR-020): a condition names a tag, fund, campaign or appeal deleted since, a custom field whose type no longer allows it, or the stored filter no longer passes the grammar; or the list is deleted. Type `https://docs.operationcharity.org/problems/saved-list-needs-fixing`, with a pointer and a message per condition in `errors`. Restore the record or edit the list. Nothing was changed.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.
• 503 Working out a list's giving conditions took longer than 10 seconds, the gift load and the money library included (ADR-020). Nothing was changed; try again, or narrow the list. Lists are built for organizations of up to 20,000 contacts and 100,000 gifts.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
  "name": "Lapsed shelter donors",
  "description": "Gave to the shelter last fiscal year, not yet this year, and can be mailed.",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 1
          },
          "to": {
            "type": "year_end",
            "years_ago": 1
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 0
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  },
  "version": 3,
  "problems": [],
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "created_at": "2026-10-01T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Rename or change a saved list

PATCH /v1/saved-lists/{id}

Staff, admins and write keys. filter replaces the stored filter whole and is checked whole (422 with pointers); a change of filter increments version, and a save of the same filter keeps it. Of two saves at once the later wins, and the audit log keeps both. Snapshots already frozen do not change. Emits saved_list.updated.

Parameters

Request body (SavedListUpdate)

{
  "name": "Lapsed shelter donors (mail)"
}

Responses

• 200 The updated list.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
  "name": "Lapsed shelter donors",
  "description": "Gave to the shelter last fiscal year, not yet this year, and can be mailed.",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 1
          },
          "to": {
            "type": "year_end",
            "years_ago": 1
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 0
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  },
  "version": 3,
  "problems": [],
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "created_at": "2026-10-01T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a saved list

DELETE /v1/saved-lists/{id}

Staff, admins and write keys. Soft delete (ADR-005): the list leaves the list of lists and is no longer worked out (its members and count answer 409); its snapshots and runs stay, and POST /v1/saved-lists/{id}/restore brings it back. Emits saved_list.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted saved list

POST /v1/saved-lists/{id}/restore

Staff, admins and write keys. Clears deleted_at and deleted_by. 409 if the list is not deleted, or if another live list now has its name (rename one of them first). Emits saved_list.updated, as every restore does (ADR-005).

Parameters

Responses

• 200 The restored list, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
  "name": "Lapsed shelter donors",
  "description": "Gave to the shelter last fiscal year, not yet this year, and can be mailed.",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 1
          },
          "to": {
            "type": "year_end",
            "years_ago": 1
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "year_start",
            "years_ago": 0
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  },
  "version": 3,
  "problems": [],
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "created_at": "2026-10-01T16:00:00Z",
  "updated_at": "2026-10-05T14:30:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Freeze a saved list's members

POST /v1/saved-lists/{id}/snapshots

Staff, admins and write keys (ADR-020). Freezes the list's live members of this moment in one statement, with the filter as evaluated (every relative date resolved against as_of, the organization's date), the list's version and the count, so the count can never disagree with the rows; a snapshot never changes. F1 sends to the snapshot its approver reviewed, and bulk actions over a list act on a snapshot. 409 while the list has problems, or when it is deleted. A list with a giving condition draws on the organization's evaluation bucket (429) and answers within 10 seconds (503). Emits saved_list_snapshot.created, without its members.

Parameters

Request body (SavedListSnapshotCreate)

{
  "name": "November appeal"
}

Responses

• 201 The snapshot.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 The saved list can't be worked out now (ADR-020): a condition names a tag, fund, campaign or appeal deleted since, a custom field whose type no longer allows it, or the stored filter no longer passes the grammar; or the list is deleted. Type `https://docs.operationcharity.org/problems/saved-list-needs-fixing`, with a pointer and a message per condition in `errors`. Restore the record or edit the list. Nothing was changed.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.
• 503 Working out a list's giving conditions took longer than 10 seconds, the gift load and the money library included (ADR-020). Nothing was changed; try again, or narrow the list. Lists are built for organizations of up to 20,000 contacts and 100,000 gifts.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7d01",
  "saved_list_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
  "list_version": 3,
  "name": "November appeal",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "date",
            "date": "2025-07-01"
          },
          "to": {
            "type": "date",
            "date": "2026-06-30"
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "date",
            "date": "2026-07-01"
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  },
  "as_of": "2026-10-13",
  "member_count": 112,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "api_key_id": null,
  "created_at": "2026-10-13T15:00:00Z"
}

List snapshots

GET /v1/saved-list-snapshots

Read access. Sorted by created_at, newest first, then id. saved_list_id keeps one list's snapshots. Their members are GET /v1/contacts?snapshot_id=. Unknown query parameters are a 400.

Parameters

Responses

• 200 A page of snapshots.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7d01",
      "saved_list_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
      "list_version": 3,
      "name": "November appeal",
      "filter": {
        "version": 1,
        "match": "all",
        "conditions": [
          {
            "field": "gave",
            "period": {
              "basis": "fiscal",
              "from": {
                "type": "date",
                "date": "2025-07-01"
              },
              "to": {
                "type": "date",
                "date": "2026-06-30"
              }
            },
            "fund_ids": [
              "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
            ]
          },
          {
            "field": "gave",
            "period": {
              "basis": "fiscal",
              "from": {
                "type": "date",
                "date": "2026-07-01"
              },
              "to": null
            },
            "not": true
          },
          {
            "field": "has_mailing_address"
          },
          {
            "field": "do_not_contact",
            "not": true
          },
          {
            "field": "tags",
            "match": "none",
            "tag_ids": [
              "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
            ]
          }
        ]
      },
      "as_of": "2026-10-13",
      "member_count": 112,
      "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
      "api_key_id": null,
      "created_at": "2026-10-13T15:00:00Z"
    }
  ],
  "next_cursor": null
}

Get a snapshot

GET /v1/saved-list-snapshots/{id}

Read access. A snapshot of a list deleted since is still returned. Unknown query parameters are a 400.

Parameters

Responses

• 200 The snapshot.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7d01",
  "saved_list_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7c01",
  "list_version": 3,
  "name": "November appeal",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "date",
            "date": "2025-07-01"
          },
          "to": {
            "type": "date",
            "date": "2026-06-30"
          }
        },
        "fund_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
        ]
      },
      {
        "field": "gave",
        "period": {
          "basis": "fiscal",
          "from": {
            "type": "date",
            "date": "2026-07-01"
          },
          "to": null
        },
        "not": true
      },
      {
        "field": "has_mailing_address"
      },
      {
        "field": "do_not_contact",
        "not": true
      },
      {
        "field": "tags",
        "match": "none",
        "tag_ids": [
          "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a02"
        ]
      }
    ]
  },
  "as_of": "2026-10-13",
  "member_count": 112,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "api_key_id": null,
  "created_at": "2026-10-13T15:00:00Z"
}

List bulk runs

GET /v1/bulk-runs

Read access. The history of bulk actions over snapshots (ADR-020), each with its status, so any of them can be undone with no time limit. Sorted by created_at, newest first, then id. snapshot_id keeps one snapshot's runs. Unknown query parameters are a 400.

Parameters

Responses

• 200 A page of runs.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7e01",
      "snapshot_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7d01",
      "action": "add_tag",
      "tag_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
      "status": "completed",
      "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
      "api_key_id": null,
      "call_count": 1,
      "changed_count": 104,
      "created_at": "2026-10-13T15:05:00Z",
      "completed_at": "2026-10-13T15:05:00Z",
      "undo_started_at": null,
      "undone_by": null,
      "undone_by_api_key_id": null,
      "undone_at": null,
      "cursor": null
    }
  ],
  "next_cursor": null
}

Get a bulk run

GET /v1/bulk-runs/{id}

Read access. While the run is running, whoever started it gets a fresh cursor, so a run left longer than a cursor lives (24 hours) can continue with POST /v1/contacts/bulk; anyone else, and any run that is not running, gets null. Unknown query parameters are a 400.

Parameters

Responses

• 200 The run.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7e01",
  "snapshot_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7d01",
  "action": "add_tag",
  "tag_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
  "status": "completed",
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "api_key_id": null,
  "call_count": 1,
  "changed_count": 104,
  "created_at": "2026-10-13T15:05:00Z",
  "completed_at": "2026-10-13T15:05:00Z",
  "undo_started_at": null,
  "undone_by": null,
  "undone_by_api_key_id": null,
  "undone_at": null,
  "cursor": null
}

Undo a bulk run

POST /v1/bulk-runs/{id}/undo

Reverses exactly the contacts the run recorded as changed, 500 a call in contact id order, from the run's own history (no time limit, as an import's rollback; the calls' stored responses are not needed). It needs the access starting the run did: write access (staff, admins, write keys) for a tagging run, a signed-in admin for a delete run (API keys and staff get 403). The first call moves the run to undoing, so a run still in progress takes no more calls; call again while it answers undoing, until undone. Each call locks the run first. Undoing an add-tag run takes the tag off a contact only while that tag row is live and unchanged since the run's call; undoing a remove-tag run puts the tag back only where it is still off and unchanged since the run's call; undoing a delete run restores a contact only while it is still deleted with its call's time, with its communications and tasks, and a relationship once both its contacts are live (ADR-018). A contact changed since is unchanged and left as it is, and so is a contact whose custom fields are still an old import's text, with that reason. An undone run answers 409, and so does a tagging run whose tag was deleted, until the tag is restored. Each contact put back emits its own contact.updated.

Parameters

Responses

• 200 What this call reversed, and the run.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "bulk_run": {
    "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7e01",
    "snapshot_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7d01",
    "action": "add_tag",
    "tag_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c7a01",
    "status": "undone",
    "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
    "api_key_id": null,
    "call_count": 1,
    "changed_count": 2,
    "created_at": "2026-10-13T15:05:00Z",
    "completed_at": "2026-10-13T15:05:00Z",
    "undo_started_at": "2026-10-13T15:20:00Z",
    "undone_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
    "undone_by_api_key_id": null,
    "undone_at": "2026-10-13T15:20:00Z",
    "cursor": null
  },
  "results": [
    {
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "outcome": "changed",
      "reason": null
    },
    {
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d81",
      "outcome": "unchanged",
      "reason": "The tag was changed on this contact since the run, so it was left as it is."
    }
  ],
  "counts": {
    "changed": 1,
    "unchanged": 1
  }
}

List households

GET /v1/households

Sorted by name, then id. Soft-deleted records are excluded unless include_deleted=true.

Parameters

Responses

• 200 A page of households.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
      "name": "The Nakamura household",
      "address_line1": "1420 Spruce St",
      "address_line2": null,
      "city": "Denver",
      "region": "CO",
      "postal_code": "80205",
      "country": "US",
      "created_at": "2026-03-01T15:00:00Z",
      "updated_at": "2026-03-01T15:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create a household

POST /v1/households

Emits household.created.

Request body (HouseholdCreate)

{
  "name": "The Nakamura household",
  "address_line1": "1420 Spruce St",
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205"
}

Responses

• 201 The new household.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "name": "The Nakamura household",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-03-01T15:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a household

GET /v1/households/{id}

A soft-deleted household is still returned, with deleted_at set, so undo screens can show it. Lists hide it.

Parameters

Responses

• 200 The household.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "name": "The Nakamura household",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-03-01T15:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update a household

PATCH /v1/households/{id}

Emits household.updated.

Parameters

Request body (HouseholdUpdate)

{
  "address_line1": "1420 Spruce St",
  "postal_code": "80205"
}

Responses

• 200 The updated household.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "name": "The Nakamura household",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-03-01T15:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a household

DELETE /v1/households/{id}

Soft delete (ADR-005): sets deleted_at, hides the household from lists and keeps members' household_id intact so a restore puts the household back together. Emits household.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted household

POST /v1/households/{id}/restore

Clears deleted_at and deleted_by. 409 if the household is not deleted. Emits household.updated.

Parameters

Responses

• 200 The restored household, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d04",
  "name": "The Nakamura household",
  "address_line1": "1420 Spruce St",
  "address_line2": null,
  "city": "Denver",
  "region": "CO",
  "postal_code": "80205",
  "country": "US",
  "created_at": "2026-03-01T15:00:00Z",
  "updated_at": "2026-03-01T15:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List contact relationships

GET /v1/contact-relationships

Sorted by created_at, then id. Soft-deleted records are excluded unless include_deleted=true.

Parameters

Responses

• 200 A page of relationships.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d23",
      "from_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "to_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
      "relationship": "spouse",
      "created_at": "2026-03-01T15:05:00Z",
      "updated_at": "2026-03-01T15:05:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create a contact relationship

POST /v1/contact-relationships

Directional (from → to). Record the reverse separately if needed. Emits contact_relationship.created.

Request body (ContactRelationshipCreate)

{
  "from_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "to_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "relationship": "spouse"
}

Responses

• 201 The new relationship.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d23",
  "from_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "to_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "relationship": "spouse",
  "created_at": "2026-03-01T15:05:00Z",
  "updated_at": "2026-03-01T15:05:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a contact relationship

GET /v1/contact-relationships/{id}

A soft-deleted contact relationship is still returned, with deleted_at set, so undo screens can show it. Lists hide it.

Parameters

Responses

• 200 The relationship.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d23",
  "from_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "to_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "relationship": "spouse",
  "created_at": "2026-03-01T15:05:00Z",
  "updated_at": "2026-03-01T15:05:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update a contact relationship

PATCH /v1/contact-relationships/{id}

Only the label can change. Emits contact_relationship.updated.

Parameters

Request body (ContactRelationshipUpdate)

{
  "relationship": "partner"
}

Responses

• 200 The updated relationship.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d23",
  "from_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "to_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "relationship": "spouse",
  "created_at": "2026-03-01T15:05:00Z",
  "updated_at": "2026-03-01T15:05:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a contact relationship

DELETE /v1/contact-relationships/{id}

Soft delete (ADR-005): sets deleted_at; restore with POST /v1/contact-relationships/{id}/restore. Emits contact_relationship.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted contact relationship

POST /v1/contact-relationships/{id}/restore

Clears deleted_at and deleted_by. 409 if the contact relationship is not deleted. Emits contact_relationship.updated.

Parameters

Responses

• 200 The restored contact relationship, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d23",
  "from_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "to_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "relationship": "spouse",
  "created_at": "2026-03-01T15:05:00Z",
  "updated_at": "2026-03-01T15:05:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List funds

GET /v1/funds

Sorted by name, then id. Inactive funds are included unless active=true. Soft-deleted records are excluded unless include_deleted=true.

Parameters

Responses

• 200 A page of funds.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
      "name": "General fund",
      "code": "GEN",
      "restriction": "unrestricted",
      "purpose": null,
      "restriction_release_date": null,
      "is_default": true,
      "active": true,
      "created_at": "2026-01-15T16:00:00Z",
      "updated_at": "2026-01-15T16:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
      "name": "Winter Shelter Fund",
      "code": "SHELTER",
      "restriction": "purpose",
      "purpose": "Overnight shelter operations from November through March",
      "restriction_release_date": null,
      "is_default": false,
      "active": true,
      "created_at": "2026-09-01T16:00:00Z",
      "updated_at": "2026-09-01T16:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create a fund

POST /v1/funds

Names are unique per organization (409). A purpose-restricted fund should state its purpose; a time-restricted fund its release date. Emits fund.created.

Request body (FundCreate)

{
  "name": "Winter Shelter Fund",
  "code": "SHELTER",
  "restriction": "purpose",
  "purpose": "Overnight shelter operations from November through March"
}

Responses

• 201 The new fund.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Winter Shelter Fund",
  "code": "SHELTER",
  "restriction": "purpose",
  "purpose": "Overnight shelter operations from November through March",
  "restriction_release_date": null,
  "is_default": false,
  "active": true,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a fund

GET /v1/funds/{id}

A soft-deleted fund is still returned, with deleted_at set, so undo screens can show it. Lists hide it.

Parameters

Responses

• 200 The fund.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Winter Shelter Fund",
  "code": "SHELTER",
  "restriction": "purpose",
  "purpose": "Overnight shelter operations from November through March",
  "restriction_release_date": null,
  "is_default": false,
  "active": true,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update a fund

PATCH /v1/funds/{id}

Changing restriction on a fund that has gifts is refused (409). Emits fund.updated.

Parameters

Request body (FundUpdate)

{
  "purpose": "Overnight shelter operations from November through March"
}

Responses

• 200 The updated fund.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Winter Shelter Fund",
  "code": "SHELTER",
  "restriction": "purpose",
  "purpose": "Overnight shelter operations from November through March",
  "restriction_release_date": null,
  "is_default": false,
  "active": true,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a fund

DELETE /v1/funds/{id}

Soft delete (ADR-005): sets deleted_at and hides the fund from lists; restore with POST /v1/funds/{id}/restore. Still refused (409) for the default fund or any fund with gifts, so balances and reports stay intact; set active=false instead. Also refused (409, ADR-013) while a live donation form offers the fund or a recurring donation that has not ended gives to it; the detail names the form. Emits fund.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Fund ledger

GET /v1/funds/{id}/ledger

Every gift into the fund and every adjustment that changes its balance between date_from and date_to (inclusive; date_to defaults to today in the organization's timezone, date_from to the beginning), with a running balance, so a bookkeeper can tie out the restricted-balances report (B6). opening_balance_cents carries everything before date_from; closing_balance_cents equals the report's remaining_cents with as_of = date_to. Same arithmetic as the report and hard credit only. Sorted by date ascending, then gifts before adjustments, then id (then line type, since a reallocation within one fund has two lines); balance_cents is the running balance in that order. A soft-deleted fund still answers.

Parameters

Responses

• 200 A page of ledger lines.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "fund_name": "Winter Shelter Fund",
  "restriction": "purpose",
  "date_from": "2026-10-01",
  "date_to": "2026-10-31",
  "opening_balance_cents": 840000,
  "closing_balance_cents": 850000,
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "source": "gift",
      "type": "gift",
      "date": "2026-10-02",
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "adjustment_id": null,
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "contact_name": "Aiko Tanaka",
      "amount_cents": 25000,
      "balance_cents": 865000,
      "counterpart_fund_id": null,
      "reason": null,
      "exception_reason": null,
      "consent_reference": null
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d14",
      "source": "adjustment",
      "type": "reallocate_out",
      "date": "2026-10-05",
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "adjustment_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d14",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "contact_name": "Aiko Tanaka",
      "amount_cents": -5000,
      "balance_cents": 860000,
      "counterpart_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
      "reason": "Donor asked to move part of the gift",
      "exception_reason": null,
      "consent_reference": "Donor email of 2026-10-04"
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d15",
      "source": "adjustment",
      "type": "release_restriction",
      "date": "2026-10-20",
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d16",
      "adjustment_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d15",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
      "contact_name": "Cedar Ridge Community Foundation",
      "amount_cents": -10000,
      "balance_cents": 850000,
      "counterpart_fund_id": null,
      "reason": "October shelter staffing paid",
      "exception_reason": null,
      "consent_reference": null
    }
  ],
  "next_cursor": null
}

Restore a deleted fund

POST /v1/funds/{id}/restore

Clears deleted_at and deleted_by. 409 if the fund is not deleted. Emits fund.updated.

Parameters

Responses

• 200 The restored fund, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Winter Shelter Fund",
  "code": "SHELTER",
  "restriction": "purpose",
  "purpose": "Overnight shelter operations from November through March",
  "restriction_release_date": null,
  "is_default": false,
  "active": true,
  "created_at": "2026-09-01T16:00:00Z",
  "updated_at": "2026-09-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List campaigns

GET /v1/campaigns

Sorted by starts_on descending (nulls last), then id. Soft-deleted records are excluded unless include_deleted=true.

Parameters

Responses

• 200 A page of campaigns.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
      "name": "Winter 2026",
      "goal_cents": 5000000,
      "starts_on": "2026-10-01",
      "ends_on": "2026-12-31",
      "default_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
      "created_at": "2026-09-15T16:00:00Z",
      "updated_at": "2026-09-15T16:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create a campaign

POST /v1/campaigns

Names are unique per organization (409). Emits campaign.created.

Request body (CampaignCreate)

{
  "name": "Winter 2026",
  "goal_cents": 5000000,
  "starts_on": "2026-10-01",
  "ends_on": "2026-12-31",
  "default_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09"
}

Responses

• 201 The new campaign.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "Winter 2026",
  "goal_cents": 5000000,
  "starts_on": "2026-10-01",
  "ends_on": "2026-12-31",
  "default_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "created_at": "2026-09-15T16:00:00Z",
  "updated_at": "2026-09-15T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a campaign

GET /v1/campaigns/{id}

A soft-deleted campaign is still returned, with deleted_at set, so undo screens can show it. Lists hide it.

Parameters

Responses

• 200 The campaign.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "Winter 2026",
  "goal_cents": 5000000,
  "starts_on": "2026-10-01",
  "ends_on": "2026-12-31",
  "default_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "created_at": "2026-09-15T16:00:00Z",
  "updated_at": "2026-09-15T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update a campaign

PATCH /v1/campaigns/{id}

Emits campaign.updated.

Parameters

Request body (CampaignUpdate)

{
  "goal_cents": 5000000
}

Responses

• 200 The updated campaign.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "Winter 2026",
  "goal_cents": 5000000,
  "starts_on": "2026-10-01",
  "ends_on": "2026-12-31",
  "default_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "created_at": "2026-09-15T16:00:00Z",
  "updated_at": "2026-09-15T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a campaign

DELETE /v1/campaigns/{id}

Soft delete (ADR-005): sets deleted_at and hides the campaign from lists. Gifts and appeals keep their campaign_id so a restore is a true undo. Refused (409, ADR-013) while a live donation form is set to the campaign or a recurring donation that has not ended is credited to it; the detail names the form. Emits campaign.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted campaign

POST /v1/campaigns/{id}/restore

Clears deleted_at and deleted_by. 409 if the campaign is not deleted. Emits campaign.updated.

Parameters

Responses

• 200 The restored campaign, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "Winter 2026",
  "goal_cents": 5000000,
  "starts_on": "2026-10-01",
  "ends_on": "2026-12-31",
  "default_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "created_at": "2026-09-15T16:00:00Z",
  "updated_at": "2026-09-15T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List appeals

GET /v1/appeals

Sorted by sent_on descending (nulls last), then id. Soft-deleted records are excluded unless include_deleted=true.

Parameters

Responses

• 200 A page of appeals.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
      "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
      "name": "September letter",
      "channel": "letter",
      "sent_on": "2026-09-28",
      "cost_cents": 84000,
      "created_at": "2026-09-15T17:00:00Z",
      "updated_at": "2026-09-28T16:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create an appeal

POST /v1/appeals

Names are unique per organization (409). Emits appeal.created.

Request body (AppealCreate)

{
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "September letter",
  "channel": "letter",
  "sent_on": "2026-09-28",
  "cost_cents": 84000
}

Responses

• 201 The new appeal.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "September letter",
  "channel": "letter",
  "sent_on": "2026-09-28",
  "cost_cents": 84000,
  "created_at": "2026-09-15T17:00:00Z",
  "updated_at": "2026-09-28T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get an appeal

GET /v1/appeals/{id}

A soft-deleted appeal is still returned, with deleted_at set, so undo screens can show it. Lists hide it.

Parameters

Responses

• 200 The appeal.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "September letter",
  "channel": "letter",
  "sent_on": "2026-09-28",
  "cost_cents": 84000,
  "created_at": "2026-09-15T17:00:00Z",
  "updated_at": "2026-09-28T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update an appeal

PATCH /v1/appeals/{id}

Emits appeal.updated.

Parameters

Request body (AppealUpdate)

{
  "cost_cents": 84000,
  "sent_on": "2026-09-28"
}

Responses

• 200 The updated appeal.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "September letter",
  "channel": "letter",
  "sent_on": "2026-09-28",
  "cost_cents": 84000,
  "created_at": "2026-09-15T17:00:00Z",
  "updated_at": "2026-09-28T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete an appeal

DELETE /v1/appeals/{id}

Soft delete (ADR-005): sets deleted_at and hides the appeal from lists. Gifts keep their appeal_id so a restore is a true undo. Refused (409, ADR-013) while a live donation form is set to the appeal or a recurring donation that has not ended is credited to it; the detail names the form. Emits appeal.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted appeal

POST /v1/appeals/{id}/restore

Clears deleted_at and deleted_by. 409 if the appeal is not deleted. Emits appeal.updated.

Parameters

Responses

• 200 The restored appeal, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "name": "September letter",
  "channel": "letter",
  "sent_on": "2026-09-28",
  "cost_cents": 84000,
  "created_at": "2026-09-15T17:00:00Z",
  "updated_at": "2026-09-28T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List gifts

GET /v1/gifts

Sorted by received_on descending, then id descending. donation_form_id lists the gifts made through one donation form; recurring_donation_id lists the charges of one recurring donation (ADR-013); batch_id lists every gift entered into one deposit batch, voided ones included (ADR-019; GET /v1/gift-batches/{id}/entries lists them in the order entered, as the batch counts them).

Parameters

Responses

• 200 A page of gifts.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "contact_name": "Aiko Nakamura",
      "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
      "fund_name": "Winter Shelter Fund",
      "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
      "campaign_name": "Winter 2026",
      "appeal_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
      "appeal_name": "September letter",
      "grant_id": null,
      "kind": "one_time",
      "status": "posted",
      "amount_cents": 5000,
      "fair_market_value_cents": 0,
      "fee_covered_cents": 0,
      "received_on": "2026-10-04",
      "contribution_date": "2026-10-04",
      "payment_method": "card",
      "external_ref": "pi_3Q8kLm2eZvKYlo2C1aBcDeFg",
      "in_kind_description": null,
      "property_description": null,
      "book_fair_value_cents": null,
      "valuation_method": null,
      "nonfinancial_category": null,
      "pledge_id": null,
      "tribute_type": null,
      "tribute_name": null,
      "notify_contact_id": null,
      "notes": "Gave through the website after the September letter.",
      "receipt_required": false,
      "donation_form_id": null,
      "donation_form_title": null,
      "recurring_donation_id": null,
      "recurring_interval": null,
      "batch_id": null,
      "batch_name": null,
      "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
      "created_at": "2026-10-04T22:15:00Z",
      "updated_at": "2026-10-04T22:15:00Z"
    }
  ],
  "next_cursor": null
}

Record a gift

POST /v1/giftsIdempotency-Key required

Gifts are append-only: there is no PATCH or DELETE /v1/gifts/{id}. To refund, void, correct an amount, move money between funds or release a restriction, create a gift adjustment. Requires Idempotency-Key. Creates the thank-you task and, when the amount is $250 or more, flags the receipt as required. Emits gift.created. With batch_id the gift is entered into an open deposit batch (ADR-019): it must have an amount (never in-kind) and may not be a pledge; a missing or deleted batch, or a gift that cannot join, is 422 on /batch_id, and a closed batch is 409. A batch holds checks and cash only: any other payment method, or none, is 422 on /payment_method. A gift received after the batch's deposit date is 422 on /received_on (received on the deposit date itself, it joins). A check's number goes in external_ref: 1 to 10 digits, for every check gift in a batch or not; anything else (such as the line along the bottom of the check, which holds the donor's bank account numbers) is 422 on /external_ref. Cash in a batch carries no other reference either.

Parameters

Request body (GiftCreate)

{
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "appeal_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
  "kind": "one_time",
  "amount_cents": 5000,
  "fair_market_value_cents": 0,
  "fee_covered_cents": 0,
  "received_on": "2026-10-04",
  "payment_method": "card",
  "external_ref": "pi_3Q8kLm2eZvKYlo2C1aBcDeFg",
  "notes": "Gave through the website after the September letter."
}

Responses

• 201 The recorded gift.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "contact_name": "Aiko Nakamura",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "fund_name": "Winter Shelter Fund",
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "campaign_name": "Winter 2026",
  "appeal_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
  "appeal_name": "September letter",
  "grant_id": null,
  "kind": "one_time",
  "status": "posted",
  "amount_cents": 5000,
  "fair_market_value_cents": 0,
  "fee_covered_cents": 0,
  "received_on": "2026-10-04",
  "contribution_date": "2026-10-04",
  "payment_method": "card",
  "external_ref": "pi_3Q8kLm2eZvKYlo2C1aBcDeFg",
  "in_kind_description": null,
  "property_description": null,
  "book_fair_value_cents": null,
  "valuation_method": null,
  "nonfinancial_category": null,
  "pledge_id": null,
  "tribute_type": null,
  "tribute_name": null,
  "notify_contact_id": null,
  "notes": "Gave through the website after the September letter.",
  "receipt_required": false,
  "donation_form_id": null,
  "donation_form_title": null,
  "recurring_donation_id": null,
  "recurring_interval": null,
  "batch_id": null,
  "batch_name": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-04T22:15:00Z",
  "updated_at": "2026-10-04T22:15:00Z"
}

Get a gift

GET /v1/gifts/{id}

Online gifts (ADR-013) carry donation_form_id, recurring_donation_id for each charge of a recurring donation, the Stripe payment intent in external_ref and created_by null. A gift entered into a deposit batch (ADR-019) carries batch_id and batch_name, and a check its number in external_ref.

Parameters

Responses

• 200 The gift.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
  "contact_name": "Aiko Nakamura",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "fund_name": "Winter Shelter Fund",
  "campaign_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d10",
  "campaign_name": "Winter 2026",
  "appeal_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d11",
  "appeal_name": "September letter",
  "grant_id": null,
  "kind": "one_time",
  "status": "posted",
  "amount_cents": 5000,
  "fair_market_value_cents": 0,
  "fee_covered_cents": 0,
  "received_on": "2026-10-04",
  "contribution_date": "2026-10-04",
  "payment_method": "card",
  "external_ref": "pi_3Q8kLm2eZvKYlo2C1aBcDeFg",
  "in_kind_description": null,
  "property_description": null,
  "book_fair_value_cents": null,
  "valuation_method": null,
  "nonfinancial_category": null,
  "pledge_id": null,
  "tribute_type": null,
  "tribute_name": null,
  "notify_contact_id": null,
  "notes": "Gave through the website after the September letter.",
  "receipt_required": false,
  "donation_form_id": null,
  "donation_form_title": null,
  "recurring_donation_id": null,
  "recurring_interval": null,
  "batch_id": null,
  "batch_name": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-04T22:15:00Z",
  "updated_at": "2026-10-04T22:15:00Z"
}

Update an in-kind gift's valuation

PATCH /v1/gifts/{id}/valuation

Sets the internal valuation (book_fair_value_cents, valuation_method, nonfinancial_category) or the printed property_description of a posted in-kind gift, for example when an appraisal arrives (ADR-008). These are the only gift columns the append-only guard lets change; the change is written to the audit log and emits gift.updated. 422 for a cash gift; 409 when the gift is no longer posted or a description change follows an issued receipt.

Parameters

Request body (GiftValuationUpdate)

{
  "book_fair_value_cents": 42000,
  "valuation_method": "independent appraisal"
}

Responses

• 200 The gift with its new valuation.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d23",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
  "contact_name": "Cedar Ridge Community Foundation",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
  "fund_name": "General fund",
  "campaign_id": null,
  "campaign_name": null,
  "appeal_id": null,
  "appeal_name": null,
  "grant_id": null,
  "kind": "in_kind",
  "status": "posted",
  "amount_cents": null,
  "fair_market_value_cents": 0,
  "fee_covered_cents": 0,
  "received_on": "2026-11-04",
  "contribution_date": "2026-11-04",
  "payment_method": "in_kind",
  "external_ref": null,
  "in_kind_description": "40 cases canned vegetables, delivered to the pantry",
  "property_description": "40 cases of canned vegetables",
  "book_fair_value_cents": 35000,
  "valuation_method": "comparable retail prices",
  "nonfinancial_category": "food",
  "pledge_id": null,
  "tribute_type": null,
  "tribute_name": null,
  "notify_contact_id": null,
  "notes": null,
  "receipt_required": true,
  "donation_form_id": null,
  "donation_form_title": null,
  "recurring_donation_id": null,
  "recurring_interval": null,
  "batch_id": null,
  "batch_name": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-11-04T18:00:00Z",
  "updated_at": "2026-11-04T18:00:00Z"
}

List gift adjustments

GET /v1/gift-adjustments

Sorted by effective_on descending, then id descending.

Parameters

Responses

• 200 A page of adjustments.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d14",
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "kind": "reallocate",
      "amount_cents": 5000,
      "from_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
      "to_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
      "effective_on": "2026-10-05",
      "reason": "Donor asked that the gift be unrestricted.",
      "exception_reason": null,
      "consent_reference": "Donor email of 2026-10-03, filed in the donor record",
      "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
      "created_at": "2026-10-05T14:30:00Z",
      "updated_at": "2026-10-05T14:30:00Z"
    }
  ],
  "next_cursor": null
}

Record a gift adjustment

POST /v1/gift-adjustmentsIdempotency-Key required

Adjustments are append-only too. Requires Idempotency-Key. A void or full refund also updates the gift's status. A correct_amount that would take a gift in an open deposit batch to $0.00 is 422 on /amount_cents (void it instead; see GiftAdjustmentCreate). Emits gift_adjustment.created.

Parameters

Request body (GiftAdjustmentCreate)

{
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "kind": "reallocate",
  "amount_cents": 5000,
  "to_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
  "effective_on": "2026-10-05",
  "reason": "Donor asked that the gift be unrestricted.",
  "consent_reference": "Donor email of 2026-10-03, filed in the donor record"
}

Responses

• 201 The recorded adjustment.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d14",
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "kind": "reallocate",
  "amount_cents": 5000,
  "from_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "to_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
  "effective_on": "2026-10-05",
  "reason": "Donor asked that the gift be unrestricted.",
  "exception_reason": null,
  "consent_reference": "Donor email of 2026-10-03, filed in the donor record",
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "created_at": "2026-10-05T14:30:00Z",
  "updated_at": "2026-10-05T14:30:00Z"
}

Get a gift adjustment

GET /v1/gift-adjustments/{id}

Parameters

Responses

• 200 The adjustment.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d14",
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "kind": "reallocate",
  "amount_cents": 5000,
  "from_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "to_fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d08",
  "effective_on": "2026-10-05",
  "reason": "Donor asked that the gift be unrestricted.",
  "exception_reason": null,
  "consent_reference": "Donor email of 2026-10-03, filed in the donor record",
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "created_at": "2026-10-05T14:30:00Z",
  "updated_at": "2026-10-05T14:30:00Z"
}

List deposit batches

GET /v1/gift-batches

Sorted by deposit_date descending, then id descending. status lists open or closed batches; date_from and date_to bound the deposit date. Each batch carries its entered count and total and the difference from the expected ones. Soft-deleted batches are excluded unless include_deleted=true (admin only).

Parameters

Responses

• 200 A page of batches.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d71",
      "name": "Sunday collection, Oct 12",
      "deposit_date": "2026-10-12",
      "expected_count": 3,
      "expected_total_cents": 22500,
      "entered_count": 2,
      "entered_total_cents": 15000,
      "count_difference": 1,
      "total_difference_cents": 7500,
      "balanced": false,
      "status": "open",
      "notes": "Plate and envelopes from the 9:30 and 11:00 services.",
      "closed_at": null,
      "closed_by": null,
      "reopened_at": null,
      "reopened_by": null,
      "reopen_reason": null,
      "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
      "created_at": "2026-10-12T16:00:00Z",
      "updated_at": "2026-10-12T16:06:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Start a deposit batch

POST /v1/gift-batchesIdempotency-Key required

Starts an open batch with the deposit's expected count and total (write access). expected_total_cents below expected_count can never balance and is 422. Requires Idempotency-Key, so a retried request never starts a second batch for one deposit. Emits gift_batch.created.

Parameters

Request body (GiftBatchCreate)

{
  "name": "Sunday collection, Oct 12",
  "deposit_date": "2026-10-12",
  "expected_count": 3,
  "expected_total_cents": 22500,
  "notes": "Plate and envelopes from the 9:30 and 11:00 services."
}

Responses

• 201 The new batch, open and empty.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d71",
  "name": "Sunday collection, Oct 12",
  "deposit_date": "2026-10-12",
  "expected_count": 3,
  "expected_total_cents": 22500,
  "entered_count": 0,
  "entered_total_cents": 0,
  "count_difference": 3,
  "total_difference_cents": 22500,
  "balanced": false,
  "status": "open",
  "notes": "Plate and envelopes from the 9:30 and 11:00 services.",
  "closed_at": null,
  "closed_by": null,
  "reopened_at": null,
  "reopened_by": null,
  "reopen_reason": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-12T16:00:00Z",
  "updated_at": "2026-10-12T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a deposit batch

GET /v1/gift-batches/{id}

The batch with its expected and entered figures and the difference. A soft-deleted batch is still returned, with deleted_at set, so undo screens can show it.

Parameters

Responses

• 200 The batch.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d71",
  "name": "Sunday collection, Oct 12",
  "deposit_date": "2026-10-12",
  "expected_count": 3,
  "expected_total_cents": 22500,
  "entered_count": 2,
  "entered_total_cents": 15000,
  "count_difference": 1,
  "total_difference_cents": 7500,
  "balanced": false,
  "status": "open",
  "notes": "Plate and envelopes from the 9:30 and 11:00 services.",
  "closed_at": null,
  "closed_by": null,
  "reopened_at": null,
  "reopened_by": null,
  "reopen_reason": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-12T16:00:00Z",
  "updated_at": "2026-10-12T16:06:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update an open deposit batch

PATCH /v1/gift-batches/{id}

Changes the name, the deposit date, the expected count and total, or the notes while the batch is open (write access). 409 once it is closed (an admin reopens it first) or while it is deleted. Gifts already in it keep their dates (gifts are append-only), so the deposit date never moves before a gift the batch counts was received: that is 409, its detail saying how many gifts were received after the new date (a gift voided while the batch was open does not count). Emits gift_batch.updated.

Parameters

Request body (GiftBatchUpdate)

{
  "expected_total_cents": 22500
}

Responses

• 200 The updated batch.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d71",
  "name": "Sunday collection, Oct 12",
  "deposit_date": "2026-10-12",
  "expected_count": 3,
  "expected_total_cents": 22500,
  "entered_count": 2,
  "entered_total_cents": 15000,
  "count_difference": 1,
  "total_difference_cents": 7500,
  "balanced": false,
  "status": "open",
  "notes": "Plate and envelopes from the 9:30 and 11:00 services.",
  "closed_at": null,
  "closed_by": null,
  "reopened_at": null,
  "reopened_by": null,
  "reopen_reason": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-12T16:00:00Z",
  "updated_at": "2026-10-12T16:06:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete an empty deposit batch

DELETE /v1/gift-batches/{id}

Soft delete (ADR-005), only while no gift counts in the batch (every gift entered was voided while it was open, or none was entered): a batch in which a gift counts is 409, because gifts are append-only and keep their batch. Hides it from lists and keeps it readable by id; restore with POST /v1/gift-batches/{id}/restore. Write access. Emits gift_batch.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted deposit batch

POST /v1/gift-batches/{id}/restore

Clears deleted_at and deleted_by; the batch is open again. 409 if it is not deleted. Write access. Emits gift_batch.updated (ADR-005).

Parameters

Responses

• 200 The restored batch, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d72",
  "name": "Bake sale cash",
  "deposit_date": "2026-10-12",
  "expected_count": 1,
  "expected_total_cents": 4000,
  "entered_count": 0,
  "entered_total_cents": 0,
  "count_difference": 1,
  "total_difference_cents": 4000,
  "balanced": false,
  "status": "open",
  "notes": null,
  "closed_at": null,
  "closed_by": null,
  "reopened_at": null,
  "reopened_by": null,
  "reopen_reason": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-12T15:00:00Z",
  "updated_at": "2026-10-12T15:12:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Close a deposit batch that balances

POST /v1/gift-batches/{id}/close

Closes an open batch when its entered count and total equal the expected ones (balanced). Otherwise 409 https://docs.operationcharity.org/problems/gift-batch-not-balanced: the detail says what is entered against what is expected and the difference, carried also by the extension members count_difference and total_difference_cents (expected minus entered). A closed batch takes no gifts and does not change until an admin reopens it; Postgres refuses the same, and the batch row is locked while it is counted, so no gift slips in after the count. Already closed, or deleted: 409 conflict. Write access. Emits gift_batch.closed.

Parameters

Responses

• 200 The closed batch.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 The batch doesn't balance yet: type `https://docs.operationcharity.org/problems/gift-batch-not-balanced`, whose detail says what is entered against what is expected and the difference, which the extension members `count_difference` and `total_difference_cents` (integer cents) also carry, expected minus entered (ADR-019). Or the batch is already closed, or deleted (type `conflict`). Nothing was changed.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d71",
  "name": "Sunday collection, Oct 12",
  "deposit_date": "2026-10-12",
  "expected_count": 3,
  "expected_total_cents": 22500,
  "entered_count": 3,
  "entered_total_cents": 22500,
  "count_difference": 0,
  "total_difference_cents": 0,
  "balanced": true,
  "status": "closed",
  "notes": "Plate and envelopes from the 9:30 and 11:00 services.",
  "closed_at": "2026-10-12T16:20:00Z",
  "closed_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "reopened_at": null,
  "reopened_by": null,
  "reopen_reason": null,
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-12T16:00:00Z",
  "updated_at": "2026-10-12T16:20:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Reopen a closed deposit batch

POST /v1/gift-batches/{id}/reopen

Admin only: a signed-in admin (an API key gets 403). The reason is kept on the batch (reopen_reason) and written to the audit log with who reopened it and when. The batch is open again: it takes gifts and edits, and closes again only when it balances. Voids and corrections recorded while it was closed still do not count. 409 when it is not closed. Emits gift_batch.reopened.

Parameters

Request body (GiftBatchReopen)

{
  "reason": "The bank's deposit receipt shows four checks; one was left out of the batch."
}

Responses

• 200 The reopened batch.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d71",
  "name": "Sunday collection, Oct 12",
  "deposit_date": "2026-10-12",
  "expected_count": 3,
  "expected_total_cents": 22500,
  "entered_count": 3,
  "entered_total_cents": 22500,
  "count_difference": 0,
  "total_difference_cents": 0,
  "balanced": true,
  "status": "open",
  "notes": "Plate and envelopes from the 9:30 and 11:00 services.",
  "closed_at": null,
  "closed_by": null,
  "reopened_at": "2026-10-13T15:00:00Z",
  "reopened_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d02",
  "reopen_reason": "The bank's deposit receipt shows four checks; one was left out of the batch.",
  "created_by": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d03",
  "created_at": "2026-10-12T16:00:00Z",
  "updated_at": "2026-10-13T15:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List the gifts in a deposit batch

GET /v1/gift-batches/{id}/entries

Sorted by created_at ascending, then id ascending: the order the gifts were entered. Every gift entered into the batch, each as the batch counts it (GiftBatchEntry): voided entries stay in the list with counted: false. A deleted batch's entries are still listed.

Parameters

Responses

• 200 A page of entries.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d73",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "contact_name": "Aiko Nakamura",
      "received_on": "2026-10-12",
      "payment_method": "check",
      "check_number": "1001",
      "status": "posted",
      "entered_cents": 10000,
      "counted_cents": 10000,
      "counted": true,
      "created_at": "2026-10-12T16:05:00Z"
    },
    {
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d74",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "contact_name": "Aiko Nakamura",
      "received_on": "2026-10-12",
      "payment_method": "check",
      "check_number": "1001",
      "status": "voided",
      "entered_cents": 10000,
      "counted_cents": 0,
      "counted": false,
      "created_at": "2026-10-12T16:06:00Z"
    }
  ],
  "next_cursor": null
}

Download a closed batch's deposit slip

GET /v1/gift-batches/{id}/deposit-slip

The deposit slip as a PDF, drawn with the receipts' PDF tooling (ADR-009): the organization's name and address, the batch's name and deposit date, each counted check in the order entered (its number, the donor and the amount the batch counts), cash on its own line, and the total. Entries voided while the batch was open are left out; the total equals the batch's. 409 while the batch is open: close it first, so the slip lists a balanced deposit. Read access. Rate-limited to 30 requests per minute per caller, in its own bucket. Content-Disposition: attachment.

Parameters

Responses

• 200 The deposit slip.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

"%PDF-1.7 …"

List soft credits

GET /v1/soft-credits

Sorted by created_at descending, then id. Soft-deleted records are excluded unless include_deleted=true.

Parameters

Responses

• 200 A page of soft credits.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d15",
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
      "contact_name": "Kenji Nakamura",
      "amount_cents": 5000,
      "role": "household_member",
      "reason": null,
      "created_at": "2026-10-04T22:16:00Z",
      "updated_at": "2026-10-04T22:16:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create a soft credit

POST /v1/soft-credits

Credits a contact for influencing a gift without changing who gave it. Never counted in receipts or balances. Emits soft_credit.created.

Request body (SoftCreditCreate)

{
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "amount_cents": 5000,
  "role": "household_member"
}

Responses

• 201 The new soft credit.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d15",
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "contact_name": "Kenji Nakamura",
  "amount_cents": 5000,
  "role": "household_member",
  "reason": null,
  "created_at": "2026-10-04T22:16:00Z",
  "updated_at": "2026-10-04T22:16:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a soft credit

GET /v1/soft-credits/{id}

A soft-deleted soft credit is still returned, with deleted_at set, so undo screens can show it. Lists hide it.

Parameters

Responses

• 200 The soft credit.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d15",
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "contact_name": "Kenji Nakamura",
  "amount_cents": 5000,
  "role": "household_member",
  "reason": null,
  "created_at": "2026-10-04T22:16:00Z",
  "updated_at": "2026-10-04T22:16:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update a soft credit

PATCH /v1/soft-credits/{id}

Emits soft_credit.updated.

Parameters

Request body (SoftCreditUpdate)

{
  "role": "household_member",
  "reason": "Spouse; gave from the joint account."
}

Responses

• 200 The updated soft credit.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d15",
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "contact_name": "Kenji Nakamura",
  "amount_cents": 5000,
  "role": "household_member",
  "reason": null,
  "created_at": "2026-10-04T22:16:00Z",
  "updated_at": "2026-10-04T22:16:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a soft credit

DELETE /v1/soft-credits/{id}

Soft delete (ADR-005): sets deleted_at; a deleted soft credit no longer counts toward the contact's totals until restored. Emits soft_credit.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Restore a deleted soft credit

POST /v1/soft-credits/{id}/restore

Clears deleted_at and deleted_by. 409 if the soft credit is not deleted. Emits soft_credit.updated.

Parameters

Responses

• 200 The restored soft credit, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d15",
  "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
  "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d06",
  "contact_name": "Kenji Nakamura",
  "amount_cents": 5000,
  "role": "household_member",
  "reason": null,
  "created_at": "2026-10-04T22:16:00Z",
  "updated_at": "2026-10-04T22:16:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List grants

GET /v1/grants

Sorted by report_due_on ascending (nulls last), then name, then id. Soft-deleted records are excluded unless include_deleted=true.

Parameters

Responses

• 200 A page of grants.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d12",
      "funder_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
      "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
      "name": "Cedar Ridge winter shelter grant 2026",
      "status": "awarded",
      "awarded_cents": 2500000,
      "indirect_rate_bps": 1500,
      "period_start": "2026-11-01",
      "period_end": "2027-03-31",
      "allowed_uses": "Shelter staffing, utilities and bedding. No capital purchases.",
      "report_due_on": "2027-04-30",
      "next_payment_due_on": "2027-01-15",
      "notes": "Second payment on receipt of the interim report.",
      "created_at": "2026-09-20T16:00:00Z",
      "updated_at": "2026-10-01T16:00:00Z",
      "deleted_at": null,
      "deleted_by": null
    }
  ],
  "next_cursor": null
}

Create a grant

POST /v1/grants

Record grant payments as gifts of kind grant_payment with grant_id set. Emits grant.created.

Request body (GrantCreate)

{
  "funder_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Cedar Ridge winter shelter grant 2026",
  "status": "awarded",
  "awarded_cents": 2500000,
  "period_start": "2026-11-01",
  "period_end": "2027-03-31",
  "allowed_uses": "Shelter staffing, utilities and bedding. No capital purchases.",
  "report_due_on": "2027-04-30",
  "next_payment_due_on": "2027-01-15"
}

Responses

• 201 The new grant.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d12",
  "funder_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Cedar Ridge winter shelter grant 2026",
  "status": "awarded",
  "awarded_cents": 2500000,
  "indirect_rate_bps": 1500,
  "period_start": "2026-11-01",
  "period_end": "2027-03-31",
  "allowed_uses": "Shelter staffing, utilities and bedding. No capital purchases.",
  "report_due_on": "2027-04-30",
  "next_payment_due_on": "2027-01-15",
  "notes": "Second payment on receipt of the interim report.",
  "created_at": "2026-09-20T16:00:00Z",
  "updated_at": "2026-10-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Get a grant

GET /v1/grants/{id}

A soft-deleted grant is still returned, with deleted_at set, so undo screens can show it. Lists hide it.

Parameters

Responses

• 200 The grant.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d12",
  "funder_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Cedar Ridge winter shelter grant 2026",
  "status": "awarded",
  "awarded_cents": 2500000,
  "indirect_rate_bps": 1500,
  "period_start": "2026-11-01",
  "period_end": "2027-03-31",
  "allowed_uses": "Shelter staffing, utilities and bedding. No capital purchases.",
  "report_due_on": "2027-04-30",
  "next_payment_due_on": "2027-01-15",
  "notes": "Second payment on receipt of the interim report.",
  "created_at": "2026-09-20T16:00:00Z",
  "updated_at": "2026-10-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Update a grant

PATCH /v1/grants/{id}

Emits grant.updated. Moving a grant to awarded creates the grant-report task.

Parameters

Request body (GrantUpdate)

{
  "status": "awarded",
  "awarded_cents": 2500000
}

Responses

• 200 The updated grant.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 422 The body parsed but failed validation.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d12",
  "funder_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Cedar Ridge winter shelter grant 2026",
  "status": "awarded",
  "awarded_cents": 2500000,
  "indirect_rate_bps": 1500,
  "period_start": "2026-11-01",
  "period_end": "2027-03-31",
  "allowed_uses": "Shelter staffing, utilities and bedding. No capital purchases.",
  "report_due_on": "2027-04-30",
  "next_payment_due_on": "2027-01-15",
  "notes": "Second payment on receipt of the interim report.",
  "created_at": "2026-09-20T16:00:00Z",
  "updated_at": "2026-10-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

Delete a grant

DELETE /v1/grants/{id}

Soft delete (ADR-005): sets deleted_at and hides the grant from lists; restore with POST /v1/grants/{id}/restore. Still refused (409) once the grant has payments; set status to closed or declined instead. Emits grant.deleted with the row (deleted_at set).

Parameters

Responses

• 204 Deleted.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

Get a grant's position

GET /v1/grants/{id}/position

Award, period, received (payments to date net of refunds), receivable, direct and indirect costs, remaining and deadlines for one grant as of a date (B6). The same row, computed by the same code, as the grant's line on GET /v1/reports/grant-status. A soft-deleted grant still answers, so undo screens can show it.

Parameters

Responses

• 200 The grant's position.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "grant_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d12",
  "name": "Cedar Ridge winter shelter grant 2026",
  "status": "awarded",
  "funder_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
  "funder_name": "Cedar Ridge Community Foundation",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "fund_name": "Winter Shelter Fund",
  "period_start": "2026-11-01",
  "period_end": "2027-03-31",
  "report_due_on": "2027-04-30",
  "next_payment_due_on": "2027-01-15",
  "awarded_cents": 2500000,
  "received_cents": 1250000,
  "receivable_cents": 1250000,
  "spent_cents": 0,
  "indirect_rate_bps": 1500,
  "indirect_cents": 0,
  "remaining_cents": 2500000,
  "unspent_cash_cents": 1250000,
  "days_to_period_end": 177,
  "days_to_report_due": 207,
  "overspent": false,
  "deadlines": [
    {
      "kind": "next_payment_due",
      "due_on": "2027-01-15",
      "days_until": 102,
      "overdue": false,
      "reported_on": null
    },
    {
      "kind": "period_end",
      "due_on": "2027-03-31",
      "days_until": 177,
      "overdue": false,
      "reported_on": null
    },
    {
      "kind": "report_due",
      "due_on": "2027-04-30",
      "days_until": 207,
      "overdue": false,
      "reported_on": null
    }
  ],
  "next_deadline": {
    "kind": "next_payment_due",
    "due_on": "2027-01-15",
    "days_until": 102,
    "overdue": false,
    "reported_on": null
  },
  "overdue": false
}

Restore a deleted grant

POST /v1/grants/{id}/restore

Clears deleted_at and deleted_by. 409 if the grant is not deleted. Emits grant.updated.

Parameters

Responses

• 200 The restored grant, with `deleted_at` null.
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 404 No such record in this organization.
• 409 Uniqueness or state conflict, or an Idempotency-Key reused with a different body.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d12",
  "funder_contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d07",
  "fund_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d09",
  "name": "Cedar Ridge winter shelter grant 2026",
  "status": "awarded",
  "awarded_cents": 2500000,
  "indirect_rate_bps": 1500,
  "period_start": "2026-11-01",
  "period_end": "2027-03-31",
  "allowed_uses": "Shelter staffing, utilities and bedding. No capital purchases.",
  "report_due_on": "2027-04-30",
  "next_payment_due_on": "2027-01-15",
  "notes": "Second payment on receipt of the interim report.",
  "created_at": "2026-09-20T16:00:00Z",
  "updated_at": "2026-10-01T16:00:00Z",
  "deleted_at": null,
  "deleted_by": null
}

List receipts

GET /v1/receipts

Sorted by created_at descending, then id.

Parameters

Responses

• 200 A page of receipts.
• 400 Malformed request (bad cursor, unknown filter, unparseable body).
• 401 Missing, invalid, expired or revoked credential.
• 403 The credential is valid but lacks the scope or role for this operation (`forbidden`), or it is a session that has not completed two-step sign-in while the member's organization requires it or the member has an authenticator app set up (`two-step-required`, ADR-017): sign in with the code from the authenticator app, or set one up, and try again. API keys never get `two-step-required`.
• 429 Rate limit exceeded.
• 500 Something failed on our side. The request can be retried; nothing was written.

{
  "data": [
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d16",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "kind": "gift",
      "gift_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d13",
      "tax_year": null,
      "contribution_date": "2026-10-04",
      "total_cents": 5000,
      "deductible_cents": 5000,
      "goods_services_statement": "No goods or services were provided in exchange for this contribution.",
      "rendered_text": "Maple Street Food Bank\n1200 Maple Street\nDenver, CO 80202\nEIN 84-1234567\n\nContribution receipt\n\nReceipt number: 3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d16\nDate issued: October 4, 2026\n\nDonor\nAiko Nakamura\n\nContribution\nContribution date: October 4, 2026\nAmount: $50.00\nDesignated to: General fund (unrestricted)\nDeductible amount: $50.00\n\nNo goods or services were provided in exchange for this contribution.\n\nThis receipt is your written acknowledgment of this contribution for federal income tax purposes. Please keep it with your tax records.\n",
      "supersedes_receipt_id": null,
      "superseded_at": null,
      "reissue_reason": null,
      "sent_at": "2026-10-04T22:20:00Z",
      "sent_via": "email",
      "created_at": "2026-10-04T22:20:00Z",
      "updated_at": "2026-10-04T22:20:00Z"
    },
    {
      "id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d17",
      "contact_id": "3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d05",
      "kind": "year_end",
      "gift_id": null,
      "tax_year": 2026,
      "contribution_date": null,
      "total_cents": 65000,
      "deductible_cents": 62500,
      "goods_services_statement": "In exchange for these contributions you received goods or services with an estimated fair market value of $25.00. The amount of your contributions that is deductible for federal income tax purposes is limited to $625.00.",
      "rendered_text": "Maple Street Food Bank\nEIN 84-1234567\n\n2026 giving statement\n\nReceipt number: 3f9d2c1a-7b4e-4f6a-9c2d-1e5b8a7c6d17\nDate issued: January 10, 2027\n\nDonor\nAiko Nakamura\n\nContributions\nDate             Designation                                Amount\nMarch 1, 2026    General fund (unrestricted)               $350.00\nJune 15, 2026    Winter Shelter Fund (purpose-restricted)  $300.00\n\nTotal contributions: $650.00\nLess goods or services provided: $25.00\nTotal deductible: $625.00\n",
      "supersedes_receipt_id": null,
      "superseded_at": null,
      "reissue_reason": null,
      "sent_at": null,
      "sent_via": null,
      "created_at": "2027-01-10T16:00:00Z",
      "updated_at": "2027-01-10T16:00:00Z"
    }
  ],
  "next_cursor": null
}

Issue a receipt for a gift

POST /v1/receiptsIdempotency-Key required

Renders the IRS Publication 1771 acknowledgment for one posted gift using the money library (deductible amount, goods-and-services statement, designation) and freezes it: the text, HTML and a snapshot of every input are stored on the receipt and never re-rendered from live data (ADR-009). In-kind gifts print the property description and never a value. A gift has one live receipt; issuing twice returns 409. With reissue: true and a reason, the live receipt is superseded (kept, superseded_at set, audited) and a new one is issued that points at it. The organization's EIN and mailing address are required: without them the answer is 422 https://docs.operationcharity.org/problems/receipt-settings-incomplete with pointers /organization/ein and /organization/mailing_address (set them with PATCH /v1/organization). With send_via: email the receipt is also queued to be emailed to the donor in the same transaction (ADR-014), when email is set up on this deployment; otherwise it is issued and not queued (send it later with POST /v1/receipts/{id}/send). Requires Idempotency-Key. Emits receipt.issued.

Parameters