# Grain API

> Developer documentation for the Grain church accounting and donor management API.

- [Introduction](https://docs.grainledger.com/intro.md): Get started with the Grain API for church accounting and donor management.
- [Quickstart](https://docs.grainledger.com/quickstart.md): Make your first production Grain API call with an organization API key.
- [MCP (Model Context Protocol)](https://docs.grainledger.com/mcp-server.md): Read-only remote MCP for AI agents and ChatGPT connectors.
- [Authentication](https://docs.grainledger.com/authentication.md): Organization API keys and OAuth 2.1 for API access.
- [Organizations](https://docs.grainledger.com/organizations.md): How organization selection works for API keys and OAuth.
- [Pagination](https://docs.grainledger.com/pagination.md): Page through list endpoints with page and limit query parameters.
- [Errors](https://docs.grainledger.com/errors.md): HTTP status codes and error response format for the Grain API.
- [Transactions](https://docs.grainledger.com/transactions.md): Create bank and card transactions, code them to accounts, funds, and dimensions, attach receipts, and approve them.
- [Giving resources](https://docs.grainledger.com/giving.md): Work safely with donors, households, contributions, giving batches, and settlements.
- [Pledge card imports](https://docs.grainledger.com/pledge-card-imports.md): Submit structured pledge card data and review it in Grain before creating pledges.
- [List funds](https://docs.grainledger.com/api-reference/funds/list-funds.md): Returns all active, assignable funds in the authenticated organization, ordered by name. Inactive funds and summary funds (funds with subfunds) are excluded. The response is not paginated. Use each id as fundId when creating contributions or mapping giving-provider funds. Requires funds:read for org…
- [List accounts](https://docs.grainledger.com/api-reference/coding-reference-data/list-accounts.md): Returns active postable chart-of-accounts entries ordered by account number. Summary accounts are excluded. Not paginated. Requires accounts:read.
- [List dimensions](https://docs.grainledger.com/api-reference/coding-reference-data/list-dimensions.md): Returns active dimensions (such as Department, Location, or Project) with their active values. Not paginated. Requires accounts:read.
- [List vendors](https://docs.grainledger.com/api-reference/coding-reference-data/list-vendors.md): Returns active vendors ordered by name. Not paginated. Requires vendors:read.
- [List authorized organizations](https://docs.grainledger.com/api-reference/organizations/list-authorized-organizations.md): Returns organizations the current user has an active Grain-managed OAuth grant for, for this client. Does not require X-Organization-Id. Unmanaged OAuth clients and API keys cannot call this endpoint.
- [List transactions](https://docs.grainledger.com/api-reference/transactions/list-transactions.md): Returns bank, card, and manual transactions with their coding. Comma-separated ID filters match any listed ID.
- [Create transaction](https://docs.grainledger.com/api-reference/transactions/create-transaction.md): Creates an uncategorized transaction. Grain queues rule and AI categorization after creation. Use Idempotency-Key for duplicate-safe retries: the same key and body return the existing transaction (201); a different body or a deleted original returns 409. To code the transaction yourself, follow with…
- [Get transaction by ID](https://docs.grainledger.com/api-reference/transactions/get-transaction-by-id.md)
- [Delete transaction](https://docs.grainledger.com/api-reference/transactions/delete-transaction.md): Reconciled transactions cannot be deleted.
- [Update transaction](https://docs.grainledger.com/api-reference/transactions/update-transaction.md): Description, reference number, and date changes are copied to the linked journal entry. Changing the vendor re-attributes the journal entry.
- [Code or split a transaction](https://docs.grainledger.com/api-reference/transactions/code-or-split-a-transaction.md): Creates or replaces the transaction's draft journal entry. Approved transactions must be unapproved first, and reconciled transactions cannot be recoded. Returns 409 when the transaction is in an open reconciliation.
- [Uncategorize a transaction](https://docs.grainledger.com/api-reference/transactions/uncategorize-a-transaction.md): Deletes the transaction's draft journal entry and returns it to review. Approved transactions return 409; unapprove them first. Reconciled transactions cannot be uncategorized.
- [Set transaction dimensions](https://docs.grainledger.com/api-reference/transactions/set-transaction-dimensions.md): Replaces the header dimensions and mirrors them to the category line of a single-account entry. Split lines keep their own dimensions; set those with PUT /transactions/{id}/coding.
- [Approve a transaction](https://docs.grainledger.com/api-reference/transactions/approve-a-transaction.md): Posts the transaction's journal entry to the ledger. Requires the transactions:approve scope. Safe to retry; approving an approved transaction returns it unchanged. Fails when required dimensions are missing or the period is locked.
- [Unapprove a transaction](https://docs.grainledger.com/api-reference/transactions/unapprove-a-transaction.md): Returns a posted journal entry to draft so it can be recoded. Requires the transactions:approve scope. Safe to retry.
- [List transaction attachments](https://docs.grainledger.com/api-reference/transactions/list-transaction-attachments.md): Returns receipts and other documents attached to the transaction, newest first.
- [Upload a receipt](https://docs.grainledger.com/api-reference/transactions/upload-a-receipt.md): Attaches a PDF or image (JPEG, PNG, GIF, WebP, or HEIC) of up to 5 MB. Requires transactions:write.
- [Get an attachment download URL](https://docs.grainledger.com/api-reference/transactions/get-an-attachment-download-url.md): Returns a signed URL that expires after 15 minutes.
- [Delete an attachment](https://docs.grainledger.com/api-reference/transactions/delete-an-attachment.md)
- [List bills](https://docs.grainledger.com/api-reference/bills/list-bills.md)
- [Create bill](https://docs.grainledger.com/api-reference/bills/create-bill.md)
- [Get bill](https://docs.grainledger.com/api-reference/bills/get-bill.md)
- [Delete bill](https://docs.grainledger.com/api-reference/bills/delete-bill.md)
- [Update bill](https://docs.grainledger.com/api-reference/bills/update-bill.md)
- [List donors](https://docs.grainledger.com/api-reference/donors/list-donors.md)
- [Create donor](https://docs.grainledger.com/api-reference/donors/create-donor.md)
- [Get donor](https://docs.grainledger.com/api-reference/donors/get-donor.md)
- [Delete donor](https://docs.grainledger.com/api-reference/donors/delete-donor.md)
- [Update donor](https://docs.grainledger.com/api-reference/donors/update-donor.md)
- [List contributions](https://docs.grainledger.com/api-reference/contributions/list-contributions.md)
- [Create contribution](https://docs.grainledger.com/api-reference/contributions/create-contribution.md): Use Idempotency-Key for duplicate-safe retries. The same key and validated input return the existing contribution (201); different input or a deleted original returns 409. Keys are scoped to organization and OAuth application, API key, or unmanaged OAuth user. External IDs alone do not deduplicate s…
- [Get contribution](https://docs.grainledger.com/api-reference/contributions/get-contribution.md)
- [Delete contribution](https://docs.grainledger.com/api-reference/contributions/delete-contribution.md)
- [Update contribution](https://docs.grainledger.com/api-reference/contributions/update-contribution.md)
- [List settlements](https://docs.grainledger.com/api-reference/settlements/list-settlements.md): Returns recorded totals and independently calculated totals from linked contributions. dateFrom/dateTo filter the UTC calendar arrival day; dateTo is inclusive to callers.
- [Create settlement](https://docs.grainledger.com/api-reference/settlements/create-settlement.md): Creates a resource record only. It never posts a journal entry, links a bank transaction, or reconciles accounting. contributionIds and givingBatchIds are applied atomically.
- [Get settlement](https://docs.grainledger.com/api-reference/settlements/get-settlement.md)
- [Delete settlement](https://docs.grainledger.com/api-reference/settlements/delete-settlement.md): Unlinks and preserves contributions and giving batches. Accounting-frozen resources return 409.
- [Update settlement](https://docs.grainledger.com/api-reference/settlements/update-settlement.md): All relationship writes are tenant-scoped and atomic. Accounting-frozen settlements return 409.
- [List giving batches](https://docs.grainledger.com/api-reference/giving-batches/list-giving-batches.md): Returns giving batches, not pledge-card review batches. Totals are derived from current contribution membership.
- [Create giving batch](https://docs.grainledger.com/api-reference/giving-batches/create-giving-batch.md): Creates an empty or populated batch without posting accounting. contributionIds atomically replace membership.
- [Get giving batch](https://docs.grainledger.com/api-reference/giving-batches/get-giving-batch.md)
- [Delete giving batch](https://docs.grainledger.com/api-reference/giving-batches/delete-giving-batch.md): Unlinks and preserves contributions. Accounting-frozen resources return 409.
- [Update giving batch](https://docs.grainledger.com/api-reference/giving-batches/update-giving-batch.md): Recalculates totals after amount, fee, or membership changes. SETTLED is an accounting-owned state and cannot be set here.
- [Import pledge card data for review](https://docs.grainledger.com/api-reference/pledge-card-imports/import-pledge-card-data-for-review.md): Creates a pledge card review group from structured data. Rows enter the same donor matching and review workflow as scanned cards; this request does not create pledges.
- [List pledge card import reference data](https://docs.grainledger.com/api-reference/pledge-card-imports/list-pledge-card-import-reference-data.md): Returns valid scan groups, campaigns, active Grain funds, Rock campuses, and the complete mapped and unmapped Rock account catalog. Use exact IDs from this response when routing imports.
- [List pledges](https://docs.grainledger.com/api-reference/pledges/list-pledges.md)
- [Create pledge](https://docs.grainledger.com/api-reference/pledges/create-pledge.md)
- [Get pledge](https://docs.grainledger.com/api-reference/pledges/get-pledge.md)
- [Delete pledge](https://docs.grainledger.com/api-reference/pledges/delete-pledge.md)
- [Update pledge](https://docs.grainledger.com/api-reference/pledges/update-pledge.md)
- [List households](https://docs.grainledger.com/api-reference/households/list-households.md)
- [Create household](https://docs.grainledger.com/api-reference/households/create-household.md)
- [Get household](https://docs.grainledger.com/api-reference/households/get-household.md)
- [Delete household](https://docs.grainledger.com/api-reference/households/delete-household.md)
- [Update household](https://docs.grainledger.com/api-reference/households/update-household.md)
- [Add household member](https://docs.grainledger.com/api-reference/households/add-household-member.md): Moves the donor from an existing household when necessary and atomically refreshes both households. Cross-organization references are rejected.
- [Remove household member](https://docs.grainledger.com/api-reference/households/remove-household-member.md): Unlinks the donor without deleting the donor and clears primary contact when applicable.
- [Update household member](https://docs.grainledger.com/api-reference/households/update-household-member.md)

## OpenAPI Specs

- [openapi](/openapi.json)

## Optional

- [Open app](https://app.grainledger.com)
- [Support](https://grainledger.com/support)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.