{ "openapi": "3.0.3", "info": { "title": "Grain API", "description": "Church accounting and donor management API. Use an organization API key for server automation or OAuth 2.1 (Sign in with Grain) for applications acting on behalf of users. Unmanaged OAuth requests require X-Organization-Id; Grain-managed OAuth apps may list authorized organizations first. API keys infer the organization.", "version": "1.3.0" }, "servers": [ { "url": "https://api.grainledger.com", "description": "API Server" } ], "tags": [ { "name": "Funds", "description": "Active funds available for integration mapping" }, { "name": "Coding Reference Data", "description": "Accounts, dimensions, and vendors used to code transactions" }, { "name": "Transactions", "description": "Bank transactions, coding, approval, and receipts" }, { "name": "Bills", "description": "Vendor bills from creation through payment" }, { "name": "Donors", "description": "Donor records and household relationships" }, { "name": "Contributions", "description": "Giving records with fund assignment and settlement" }, { "name": "Giving Batches", "description": "Contribution groups with derived totals and lifecycle state" }, { "name": "Settlements", "description": "Provider deposits with recorded and linked-contribution totals" }, { "name": "Pledges", "description": "Pledge campaigns and fulfillment tracking" }, { "name": "Pledge Card Imports", "description": "Submit structured pledge card data for review" }, { "name": "Households", "description": "Household groupings and primary contacts" }, { "name": "Organizations", "description": "Organizations the current Grain OAuth app is authorized to access" } ], "security": [ { "ApiKeyAuth": [] }, { "GrainOAuth2": [] }, { "BearerAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "grain_live_… or grain_test_…", "description": "Organization API key created in Grain Settings → API. The key determines the organization and is limited to its assigned resource scopes. Write scopes imply the corresponding read scope." }, "GrainOAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.grainledger.com/auth/v1/oauth/authorize", "tokenUrl": "https://auth.grainledger.com/auth/v1/oauth/token", "scopes": { "openid": "OpenID Connect", "email": "Email address", "profile": "Profile information" } } } }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth access token (JWT)" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "A unique key for this import request. Retrying the same body with the same key returns the original import without creating duplicate rows.", "example": "pledge-import-2027-annual-001" }, "OrganizationId": { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required with OAuth access tokens for resource requests. Omit only for GET /api/v1/organizations. Optional with organization API keys; if supplied with an API key, it must match the key's organization.", "example": "cm123abc456def" }, "PathId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource ID", "example": "cm456def789ghi" }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 1000 }, "description": "Records per page" }, "GivingLimit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Giving records per page" } }, "schemas": { "FundListResponse": { "type": "object", "additionalProperties": false, "required": [ "funds" ], "properties": { "funds": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Grain fund ID to use as fundId." }, "name": { "type": "string", "description": "Fund name to display in a dropdown." } } } } } }, "AccountListResponse": { "type": "object", "additionalProperties": false, "required": [ "accounts" ], "properties": { "accounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "accountNumber", "name", "accountType", "parentId", "isCashAccount" ], "properties": { "id": { "type": "string", "description": "Grain account ID to use as accountId when coding." }, "accountNumber": { "type": "string" }, "name": { "type": "string" }, "accountType": { "type": "string", "enum": [ "ASSET", "LIABILITY", "NET_ASSET", "REVENUE", "EXPENSE" ] }, "parentId": { "type": "string", "nullable": true }, "isCashAccount": { "type": "boolean" } } } } } }, "DimensionListResponse": { "type": "object", "additionalProperties": false, "required": [ "dimensions" ], "properties": { "dimensions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "code", "isRequired", "values" ], "properties": { "id": { "type": "string", "description": "Use as dimensionId." }, "name": { "type": "string" }, "code": { "type": "string" }, "isRequired": { "type": "boolean", "description": "Required dimensions must be assigned before a transaction can be approved." }, "values": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "code", "parentId", "isAssignable" ], "properties": { "id": { "type": "string", "description": "Use as dimensionValueId." }, "name": { "type": "string" }, "code": { "type": "string" }, "parentId": { "type": "string", "nullable": true }, "isAssignable": { "type": "boolean", "description": "Parent values roll up for reporting and cannot be assigned." } } } } } } } } }, "VendorListResponse": { "type": "object", "additionalProperties": false, "required": [ "vendors" ], "properties": { "vendors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "is1099Required" ], "properties": { "id": { "type": "string", "description": "Use as vendorId." }, "name": { "type": "string" }, "is1099Required": { "type": "boolean" } } } } } }, "Error": { "type": "object", "description": "Every error response is valid JSON with this shape. The HTTP status code carries the outcome; `code` is a stable machine-readable form of it.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "unprocessable_entity", "payload_too_large", "rate_limited", "internal_server_error" ], "example": "forbidden" }, "message": { "type": "string", "example": "You do not have access to this organization." }, "error": { "type": "string", "deprecated": true, "description": "Deprecated alias for `message`. Read `message` instead.", "example": "You do not have access to this organization." }, "details": { "type": "object", "description": "Present for schema validation failures. Contains safe top-level field names and validation codes, never submitted values.", "properties": { "fields": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "field", "code" ], "properties": { "field": { "type": "string", "example": "amount" }, "code": { "type": "string", "example": "invalid_type" } } } } } } } }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 142 }, "totalPages": { "type": "integer", "example": 8 } } }, "AccountRelationshipSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "accountNumber", "name", "accountType" ], "properties": { "id": { "type": "string" }, "accountNumber": { "type": "string", "nullable": true }, "name": { "type": "string" }, "accountType": { "type": "string", "nullable": true } } }, "TransactionBankAccountSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "mask", "accountType" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mask": { "type": "string", "nullable": true }, "accountType": { "type": "string", "nullable": true } } }, "TransactionCodingLine": { "type": "object", "additionalProperties": false, "required": [ "id", "account", "fund", "amount", "memo", "dimensions" ], "properties": { "id": { "type": "string", "description": "Journal entry line ID." }, "account": { "$ref": "#/components/schemas/AccountRelationshipSummary", "nullable": true }, "fund": { "$ref": "#/components/schemas/FundRelationshipSummary", "nullable": true }, "amount": { "type": "number", "description": "Allocated amount. Positive values allocate the transaction; negative values offset another line." }, "memo": { "type": "string", "nullable": true }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionAssignment" } } } }, "TransactionCoding": { "type": "object", "additionalProperties": false, "required": [ "status", "journalEntryId", "entryNumber", "isSplit", "lines", "missingRequiredDimensions" ], "properties": { "status": { "type": "string", "enum": [ "UNCATEGORIZED", "CATEGORIZED", "APPROVED" ], "description": "UNCATEGORIZED has no journal entry. CATEGORIZED has a draft entry. APPROVED has a posted entry." }, "journalEntryId": { "type": "string", "nullable": true }, "entryNumber": { "type": "string", "nullable": true }, "isSplit": { "type": "boolean" }, "lines": { "type": "array", "description": "Category-side journal lines. The bank or card line is omitted.", "items": { "$ref": "#/components/schemas/TransactionCodingLine" } }, "missingRequiredDimensions": { "type": "array", "description": "Required dimensions that must be assigned before the transaction can be approved.", "items": { "type": "object", "additionalProperties": false, "required": [ "dimensionId", "dimensionName" ], "properties": { "dimensionId": { "type": "string" }, "dimensionName": { "type": "string" } } } } } }, "TransactionSuggestion": { "type": "object", "additionalProperties": false, "required": [ "account", "fund", "confidence" ], "description": "Rule or AI coding suggestion awaiting review.", "properties": { "account": { "$ref": "#/components/schemas/AccountRelationshipSummary", "nullable": true }, "fund": { "$ref": "#/components/schemas/FundRelationshipSummary", "nullable": true }, "confidence": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true } } }, "Transaction": { "type": "object", "additionalProperties": false, "required": [ "id", "externalId", "description", "amount", "direction", "transactionType", "date", "referenceNumber", "source", "reviewStatus", "isReconciled", "is1099Excluded", "bankAccount", "sourceAccount", "fund", "vendor", "dimensions", "coding", "suggestion", "attachmentCount", "canManage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true, "description": "Integrator-supplied ID, unique within the organization." }, "description": { "type": "string" }, "amount": { "type": "number", "minimum": 0, "description": "Always positive. Use direction for the sign." }, "direction": { "type": "string", "enum": [ "INFLOW", "OUTFLOW" ] }, "transactionType": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAWAL", "TRANSFER", "ADJUSTMENT" ] }, "date": { "type": "string", "format": "date-time", "description": "Calendar day represented as a UTC-midnight ISO timestamp." }, "referenceNumber": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "MANUAL", "PLAID", "IMPORT", "PLANNING_CENTER", "PUSHPAY", "TITHELY", "SUBSPLASH", "ROCK_RMS", "RAMP", "DIVVY", "OVERFLOW" ] }, "reviewStatus": { "type": "string", "enum": [ "DRAFT", "PENDING_REVIEW", "PENDING_TRANSFER_MATCH", "PENDING_TRANSFER_CONFIRM", "AUTO_CATEGORIZED", "APPROVED", "POSTED", "REJECTED" ] }, "isReconciled": { "type": "boolean" }, "is1099Excluded": { "type": "boolean" }, "bankAccount": { "$ref": "#/components/schemas/TransactionBankAccountSummary", "nullable": true, "description": "Connected bank or card feed, when the transaction came from one." }, "sourceAccount": { "$ref": "#/components/schemas/AccountRelationshipSummary", "nullable": true, "description": "Ledger cash, bank, or card account the transaction clears through." }, "fund": { "$ref": "#/components/schemas/FundRelationshipSummary", "nullable": true }, "vendor": { "$ref": "#/components/schemas/NamedResourceSummary", "nullable": true }, "dimensions": { "type": "array", "description": "Header dimensions for the transaction.", "items": { "$ref": "#/components/schemas/DimensionAssignment" } }, "coding": { "$ref": "#/components/schemas/TransactionCoding" }, "suggestion": { "$ref": "#/components/schemas/TransactionSuggestion", "nullable": true }, "attachmentCount": { "type": "integer", "minimum": 0 }, "canManage": { "type": "boolean", "description": "Whether this credential can edit the transaction." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateTransaction": { "type": "object", "additionalProperties": false, "required": [ "description", "amount", "date", "transactionType" ], "properties": { "description": { "type": "string", "minLength": 1, "example": "Weekly offering deposit" }, "amount": { "type": "number", "minimum": 0, "example": 4250 }, "date": { "type": "string", "format": "date", "example": "2026-07-01" }, "transactionType": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAWAL", "TRANSFER", "ADJUSTMENT" ], "example": "DEPOSIT", "description": "DEPOSIT records an inflow; the other types record an outflow." }, "referenceNumber": { "type": "string", "example": "DEP-2026-0701" }, "bankAccountId": { "type": "string", "description": "Connected bank or card feed account." }, "accountId": { "type": "string", "description": "Ledger cash or bank account for manual transactions." }, "fundId": { "type": "string" }, "vendorId": { "type": "string" }, "is1099Excluded": { "type": "boolean" }, "externalId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your system's ID for this transaction. Unique within the organization; a duplicate returns 409. Cannot be changed later." }, "foreignCurrency": { "type": "string" }, "foreignAmount": { "type": "number" }, "exchangeRate": { "type": "number" } } }, "UpdateTransaction": { "type": "object", "additionalProperties": false, "description": "All fields are optional. Amount, type, bank account, cash account, and fund cannot change once the transaction is coded; uncategorize it first.", "properties": { "description": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "minimum": 0 }, "date": { "type": "string", "format": "date" }, "transactionType": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAWAL", "TRANSFER", "ADJUSTMENT" ] }, "referenceNumber": { "type": "string" }, "bankAccountId": { "type": "string" }, "accountId": { "type": "string" }, "fundId": { "type": "string" }, "vendorId": { "type": "string", "nullable": true }, "is1099Excluded": { "type": "boolean" }, "foreignCurrency": { "type": "string", "nullable": true }, "foreignAmount": { "type": "number", "nullable": true }, "exchangeRate": { "type": "number", "nullable": true } } }, "SetTransactionCoding": { "type": "object", "additionalProperties": false, "required": [ "lines" ], "description": "Replaces the transaction's coding. Line amounts must sum to the transaction amount. One line codes to a single account; several lines split the transaction.", "properties": { "lines": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "object", "additionalProperties": false, "required": [ "accountId", "amount" ], "properties": { "accountId": { "type": "string", "minLength": 1, "description": "Active postable account from GET /accounts. Cannot be the transaction's own bank or card account." }, "fundId": { "type": "string", "minLength": 1, "description": "Defaults to defaultFundId, then the transaction's fund, then the organization default fund." }, "amount": { "type": "number", "description": "Non-zero. Negative amounts offset other lines, such as a refund inside a split." }, "memo": { "type": "string", "maxLength": 2000 }, "dimensions": { "type": "array", "maxItems": 50, "description": "Line dimensions. When omitted, the line inherits the transaction's header dimensions.", "items": { "$ref": "#/components/schemas/DimensionInput" } } } } }, "defaultFundId": { "type": "string", "minLength": 1 }, "entryType": { "type": "string", "enum": [ "REGULAR", "ADJUSTING", "CLOSING", "REVERSING" ], "default": "REGULAR" } } }, "SetTransactionDimensions": { "type": "object", "additionalProperties": false, "required": [ "dimensions" ], "description": "Replaces the transaction's header dimensions. Send an empty array to clear them.", "properties": { "dimensions": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/DimensionInput" } } } }, "TransactionAttachment": { "type": "object", "additionalProperties": false, "required": [ "id", "fileName", "mimeType", "fileSize", "source", "createdAt" ], "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string", "description": "HEIC uploads are stored as JPEG." }, "fileSize": { "type": "integer", "description": "Size in bytes." }, "source": { "type": "string", "nullable": true, "description": "Card platform that synced the receipt, such as RAMP. Null for uploads." }, "createdAt": { "type": "string", "format": "date-time" } } }, "TransactionAttachmentListResponse": { "type": "object", "additionalProperties": false, "required": [ "attachments" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionAttachment" } } } }, "AttachmentDownload": { "type": "object", "additionalProperties": false, "required": [ "url", "expiresAt" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Signed download URL. Do not store it; request a new one when needed." }, "expiresAt": { "type": "string", "format": "date-time" } } }, "TransactionListResponse": { "type": "object", "additionalProperties": false, "required": [ "transactions", "pagination" ], "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Bill": { "type": "object", "properties": { "id": { "type": "string" }, "billNumber": { "type": "string" }, "billDate": { "type": "string", "format": "date-time" }, "dueDate": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "postingMode": { "type": "string", "enum": [ "STANDARD", "OPENING_PAYABLE" ] }, "paidAmount": { "type": "number" }, "creditedAmount": { "type": "number" }, "remainingAmount": { "type": "number" }, "status": { "type": "string" }, "vendorId": { "type": "string", "nullable": true }, "fundId": { "type": "string", "nullable": true } } }, "CreateBill": { "type": "object", "required": [ "billNumber", "billDate", "amount", "dueDate" ], "properties": { "billNumber": { "type": "string", "example": "INV-1042" }, "billDate": { "type": "string", "format": "date", "example": "2026-06-15" }, "dueDate": { "type": "string", "format": "date", "example": "2026-07-15" }, "amount": { "type": "number", "example": 850 }, "vendorId": { "type": "string" }, "fundId": { "type": "string" }, "notes": { "type": "string", "example": "HVAC maintenance contract" } } }, "BillListResponse": { "type": "object", "properties": { "bills": { "type": "array", "items": { "$ref": "#/components/schemas/Bill" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "DonorSummary": { "type": "object", "description": "Compact donor identity, household, membership, and giving summary used in list and relationship responses.", "properties": { "id": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "organizationName": { "type": "string", "nullable": true }, "donorType": { "type": "string", "enum": [ "INDIVIDUAL", "HOUSEHOLD", "ORGANIZATION", "DAF_CUSTODIAN", "FOUNDATION", "ESTATE" ] }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "householdRef": { "type": "string", "nullable": true }, "householdName": { "type": "string", "nullable": true }, "householdPosition": { "type": "string", "nullable": true, "enum": [ "PRIMARY", "SPOUSE", "CHILD", "OTHER" ] }, "isPrimaryContact": { "type": "boolean" }, "membershipStatus": { "type": "string", "nullable": true, "enum": [ "VISITOR", "REGULAR_ATTENDER", "MEMBER", "INACTIVE", "FORMER" ] }, "isActive": { "type": "boolean" }, "totalGiving": { "type": "number" }, "givingTrend": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "Donor": { "type": "object", "description": "Stable donor profile. Identity fields are null or masked unless the caller has donor identity access.", "properties": { "id": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "organizationName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "donorType": { "type": "string", "enum": [ "INDIVIDUAL", "HOUSEHOLD", "ORGANIZATION", "DAF_CUSTODIAN", "FOUNDATION", "ESTATE" ] }, "householdRef": { "type": "string", "nullable": true }, "householdName": { "type": "string", "nullable": true }, "householdPosition": { "type": "string", "nullable": true, "enum": [ "PRIMARY", "SPOUSE", "CHILD", "OTHER" ] }, "isPrimaryContact": { "type": "boolean" }, "membershipStatus": { "type": "string", "nullable": true, "enum": [ "VISITOR", "REGULAR_ATTENDER", "MEMBER", "INACTIVE", "FORMER" ] }, "isActive": { "type": "boolean" }, "totalGiving": { "type": "number" }, "contact": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "secondaryEmail": { "type": "string", "nullable": true }, "secondaryPhone": { "type": "string", "nullable": true }, "workPhone": { "type": "string", "nullable": true }, "preferredMethod": { "type": "string", "nullable": true, "enum": [ "EMAIL", "PHONE", "MAIL" ] } } }, "address": { "type": "object", "properties": { "line1": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true } } }, "profile": { "type": "object", "additionalProperties": false, "properties": { "middleName": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "suffix": { "type": "string", "nullable": true }, "birthdate": { "type": "string", "format": "date-time", "nullable": true }, "anniversary": { "type": "string", "format": "date-time", "nullable": true }, "gender": { "type": "string", "nullable": true }, "isChild": { "type": "boolean" }, "grade": { "type": "integer", "nullable": true }, "graduationYear": { "type": "integer", "nullable": true }, "schoolType": { "type": "string", "nullable": true }, "employer": { "type": "string", "nullable": true }, "occupation": { "type": "string", "nullable": true }, "photoUrl": { "type": "string", "nullable": true } } }, "membership": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "nullable": true }, "memberSince": { "type": "string", "format": "date-time", "nullable": true }, "primaryCampusId": { "type": "string", "nullable": true }, "inactivatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "communicationPreferences": { "type": "object", "properties": { "emailOptOut": { "type": "boolean" }, "mailOptOut": { "type": "boolean" }, "smsOptOut": { "type": "boolean" } } }, "household": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "primaryContactId": { "type": "string", "nullable": true }, "memberCount": { "type": "integer" } } }, "envelopeNumber": { "type": "string", "nullable": true }, "defaultCurrency": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "externalIds": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" } }, "giving": { "type": "object", "properties": { "lifetimeGiving": { "type": "number" }, "giftCount": { "type": "integer" }, "averageGift": { "type": "number" }, "firstGiftDate": { "type": "string", "format": "date-time", "nullable": true }, "lastGiftDate": { "type": "string", "format": "date-time", "nullable": true }, "segment": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "ExternalId": { "type": "object", "required": [ "platform", "externalId" ], "properties": { "platform": { "type": "string" }, "externalId": { "type": "string" } } }, "CreateDonor": { "type": "object", "additionalProperties": false, "required": [ "firstName", "lastName" ], "properties": { "firstName": { "type": "string", "example": "Sarah" }, "lastName": { "type": "string", "example": "Johnson" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "sarah@gracechurch.org" }, "phone": { "type": "string", "nullable": true, "example": "+15551234567" }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "envelopeNumber": { "type": "string", "nullable": true }, "middleName": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "suffix": { "type": "string", "nullable": true }, "birthdate": { "type": "string", "format": "date", "nullable": true, "description": "Calendar day returned as a UTC-midnight ISO timestamp." }, "anniversary": { "type": "string", "format": "date", "nullable": true, "description": "Calendar day returned as a UTC-midnight ISO timestamp." }, "gender": { "type": "string", "nullable": true, "enum": [ "MALE", "FEMALE", "UNSPECIFIED" ] }, "isChild": { "type": "boolean" }, "grade": { "type": "integer", "minimum": 1, "maximum": 12, "nullable": true }, "graduationYear": { "type": "integer", "minimum": 1900, "maximum": 2200, "nullable": true }, "schoolType": { "type": "string", "nullable": true, "enum": [ "PUBLIC", "PRIVATE", "HOMESCHOOL", "COLLEGE", "OTHER" ] }, "membershipStatus": { "type": "string", "nullable": true, "enum": [ "VISITOR", "REGULAR_ATTENDER", "MEMBER", "INACTIVE", "FORMER" ] }, "memberSince": { "type": "string", "format": "date", "nullable": true }, "primaryCampusId": { "type": "string", "nullable": true }, "inactivatedAt": { "type": "string", "format": "date-time", "nullable": true }, "photoUrl": { "type": "string", "nullable": true }, "employer": { "type": "string", "nullable": true }, "occupation": { "type": "string", "nullable": true }, "secondaryEmail": { "type": "string", "format": "email", "nullable": true }, "secondaryPhone": { "type": "string", "nullable": true }, "workPhone": { "type": "string", "nullable": true }, "householdRef": { "type": "string", "nullable": true }, "householdId": { "type": "string", "nullable": true }, "householdName": { "type": "string", "nullable": true }, "householdPosition": { "type": "string", "nullable": true, "enum": [ "PRIMARY", "SPOUSE", "CHILD", "OTHER" ] }, "preferredContactMethod": { "type": "string", "nullable": true, "enum": [ "EMAIL", "PHONE", "MAIL" ] }, "emailOptOut": { "type": "boolean" }, "mailOptOut": { "type": "boolean" }, "smsOptOut": { "type": "boolean" }, "externalIds": { "type": "object", "nullable": true, "description": "Map keyed by a supported ExternalGivingSource: PUSHPAY, PLANNING_CENTER, CCB, TITHELY, SUBSPLASH, ROCK_RMS, OVERFLOW, MANUAL, or OTHER.", "additionalProperties": false, "properties": { "PUSHPAY": { "type": "string", "minLength": 1 }, "PLANNING_CENTER": { "type": "string", "minLength": 1 }, "CCB": { "type": "string", "minLength": 1 }, "TITHELY": { "type": "string", "minLength": 1 }, "SUBSPLASH": { "type": "string", "minLength": 1 }, "ROCK_RMS": { "type": "string", "minLength": 1 }, "OVERFLOW": { "type": "string", "minLength": 1 }, "MANUAL": { "type": "string", "minLength": 1 }, "OTHER": { "type": "string", "minLength": 1 } } }, "donorType": { "type": "string", "enum": [ "INDIVIDUAL", "HOUSEHOLD", "ORGANIZATION", "DAF_CUSTODIAN", "FOUNDATION", "ESTATE" ] }, "organizationName": { "type": "string", "nullable": true }, "defaultCurrency": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true } } }, "UpdateDonor": { "type": "object", "additionalProperties": false, "description": "All fields are optional. Send null to clear a nullable field.", "properties": { "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "middleName": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "suffix": { "type": "string", "nullable": true }, "birthdate": { "type": "string", "format": "date", "nullable": true }, "anniversary": { "type": "string", "format": "date", "nullable": true }, "gender": { "type": "string", "nullable": true, "enum": [ "MALE", "FEMALE", "UNSPECIFIED" ] }, "isChild": { "type": "boolean" }, "grade": { "type": "integer", "minimum": 1, "maximum": 12, "nullable": true }, "graduationYear": { "type": "integer", "minimum": 1900, "maximum": 2200, "nullable": true }, "schoolType": { "type": "string", "nullable": true, "enum": [ "PUBLIC", "PRIVATE", "HOMESCHOOL", "COLLEGE", "OTHER" ] }, "membershipStatus": { "type": "string", "nullable": true, "enum": [ "VISITOR", "REGULAR_ATTENDER", "MEMBER", "INACTIVE", "FORMER" ] }, "memberSince": { "type": "string", "format": "date", "nullable": true }, "primaryCampusId": { "type": "string", "nullable": true }, "inactivatedAt": { "type": "string", "format": "date-time", "nullable": true }, "photoUrl": { "type": "string", "nullable": true }, "employer": { "type": "string", "nullable": true }, "occupation": { "type": "string", "nullable": true }, "secondaryEmail": { "type": "string", "format": "email", "nullable": true }, "secondaryPhone": { "type": "string", "nullable": true }, "workPhone": { "type": "string", "nullable": true }, "emailOptOut": { "type": "boolean" }, "mailOptOut": { "type": "boolean" }, "smsOptOut": { "type": "boolean" }, "householdRef": { "type": "string", "nullable": true }, "householdId": { "type": "string", "nullable": true }, "householdName": { "type": "string", "nullable": true }, "householdPosition": { "type": "string", "nullable": true, "enum": [ "PRIMARY", "SPOUSE", "CHILD", "OTHER" ] }, "preferredContactMethod": { "type": "string", "nullable": true, "enum": [ "EMAIL", "PHONE", "MAIL" ] }, "envelopeNumber": { "type": "string", "nullable": true }, "donorType": { "type": "string", "enum": [ "INDIVIDUAL", "HOUSEHOLD", "ORGANIZATION", "DAF_CUSTODIAN", "FOUNDATION", "ESTATE" ] }, "organizationName": { "type": "string", "nullable": true }, "defaultCurrency": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "externalIds": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "PUSHPAY": { "type": "string", "minLength": 1 }, "PLANNING_CENTER": { "type": "string", "minLength": 1 }, "CCB": { "type": "string", "minLength": 1 }, "TITHELY": { "type": "string", "minLength": 1 }, "SUBSPLASH": { "type": "string", "minLength": 1 }, "ROCK_RMS": { "type": "string", "minLength": 1 }, "OVERFLOW": { "type": "string", "minLength": 1 }, "MANUAL": { "type": "string", "minLength": 1 }, "OTHER": { "type": "string", "minLength": 1 } } } } }, "DonorListResponse": { "type": "object", "properties": { "donors": { "type": "array", "items": { "$ref": "#/components/schemas/DonorSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Contribution": { "type": "object", "additionalProperties": false, "description": "Contribution detail with one-level resource summaries. Provider metadata and processor billing identity are never returned.", "required": [ "id", "donorId", "sourceDonorId", "amount", "date", "fundId", "method", "isTaxDeductible", "externalSource", "givingBatchId", "settlementId", "givingMerchantId", "processingFee", "netAmount", "feeCovered", "payment", "settlementState", "sourceType", "quidProQuo", "stock", "inKind", "foreignCurrency", "foreignAmount", "exchangeRate", "donor", "sourceDonor", "fund", "batch", "settlement", "journalEntry", "merchant", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "donorId": { "type": "string", "nullable": true }, "sourceDonorId": { "type": "string", "nullable": true }, "amount": { "type": "number" }, "date": { "type": "string", "format": "date-time", "description": "Calendar day represented as a UTC-midnight ISO timestamp." }, "fundId": { "type": "string" }, "method": { "type": "string", "enum": [ "CASH", "CHECK", "CREDIT_CARD", "ACH", "ONLINE", "STOCK", "OTHER" ] }, "isTaxDeductible": { "type": "boolean" }, "checkNumber": { "type": "string", "nullable": true }, "checkDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Calendar day represented as a UTC-midnight ISO timestamp." }, "notes": { "type": "string", "nullable": true }, "memo": { "type": "string", "nullable": true }, "externalSource": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "externalDonorId": { "type": "string", "nullable": true, "description": "Provider donor identifier. Null when the caller lacks donor identity access." }, "givingEventKey": { "type": "string", "minLength": 1, "maxLength": 500, "nullable": true }, "givingBatchId": { "type": "string", "nullable": true }, "settlementId": { "type": "string", "nullable": true }, "givingMerchantId": { "type": "string", "nullable": true }, "processingFee": { "type": "number", "nullable": true }, "netAmount": { "type": "number", "nullable": true }, "feeCovered": { "type": "boolean" }, "payment": { "type": "object", "additionalProperties": false, "required": [ "status", "last4", "brand", "methodSubtype", "methodType", "source", "completedAt", "isRefunded", "refundedAt" ], "properties": { "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ] }, "last4": { "type": "string", "nullable": true }, "brand": { "type": "string", "nullable": true }, "methodSubtype": { "type": "string", "nullable": true }, "methodType": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "isRefunded": { "type": "boolean" }, "refundedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "settlementState": { "type": "object", "additionalProperties": false, "readOnly": true, "required": [ "isSettled", "settlementDate", "settlementBatch", "isCleared", "clearedAt" ], "properties": { "isSettled": { "type": "boolean" }, "settlementDate": { "type": "string", "format": "date-time", "nullable": true }, "settlementBatch": { "type": "string", "nullable": true }, "isCleared": { "type": "boolean" }, "clearedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "sourceType": { "type": "string", "nullable": true, "enum": [ "DIRECT", "DAF", "QCD_IRA", "MATCHING", "FOUNDATION", "ESTATE" ] }, "quidProQuo": { "$ref": "#/components/schemas/ContributionQuidProQuo" }, "stock": { "$ref": "#/components/schemas/ContributionStock" }, "inKind": { "$ref": "#/components/schemas/ContributionInKind" }, "foreignCurrency": { "type": "string", "nullable": true }, "foreignAmount": { "type": "number", "nullable": true }, "exchangeRate": { "type": "number", "nullable": true }, "donor": { "$ref": "#/components/schemas/DonorIdentitySummary", "nullable": true, "description": "Present only with donor identity access." }, "sourceDonor": { "$ref": "#/components/schemas/DonorIdentitySummary", "nullable": true, "description": "Present only with donor identity access." }, "fund": { "$ref": "#/components/schemas/FundRelationshipSummary", "nullable": true }, "batch": { "$ref": "#/components/schemas/BatchRelationshipSummary", "nullable": true }, "settlement": { "$ref": "#/components/schemas/SettlementRelationshipSummary", "nullable": true }, "journalEntry": { "$ref": "#/components/schemas/JournalEntryRelationshipSummary", "nullable": true }, "merchant": { "$ref": "#/components/schemas/ContributionMerchantSummary", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "ContributionSummary": { "description": "Contribution fields plus compact one-level donor, fund, batch, settlement, journal-entry, and merchant summaries.", "allOf": [ { "$ref": "#/components/schemas/Contribution" } ] }, "CreateContribution": { "type": "object", "additionalProperties": false, "required": [ "amount", "date", "fundId", "method" ], "properties": { "donorId": { "type": "string", "minLength": 1, "example": "cm456def789ghi" }, "sourceDonorId": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 250 }, "date": { "type": "string", "format": "date", "example": "2026-07-06" }, "fundId": { "type": "string", "minLength": 1, "example": "cm789ghi012jkl" }, "method": { "type": "string", "enum": [ "CASH", "CHECK", "CREDIT_CARD", "ACH", "ONLINE", "STOCK", "OTHER" ], "example": "CHECK" }, "checkNumber": { "type": "string", "example": "1042", "description": "Required when method is CHECK." }, "checkDate": { "type": "string", "format": "date", "nullable": true }, "isTaxDeductible": { "type": "boolean", "default": true }, "notes": { "type": "string" }, "memo": { "type": "string", "maxLength": 2000, "nullable": true }, "feeCovered": { "type": "boolean" }, "givingBatchId": { "type": "string", "minLength": 1, "nullable": true }, "settlementId": { "type": "string", "minLength": 1, "nullable": true }, "givingMerchantId": { "type": "string", "minLength": 1, "nullable": true }, "externalId": { "type": "string" }, "externalSource": { "type": "string", "enum": [ "PUSHPAY", "PLANNING_CENTER", "CCB", "TITHELY", "SUBSPLASH", "ROCK_RMS", "OVERFLOW", "MANUAL", "OTHER" ] }, "externalDonorId": { "type": "string", "maxLength": 500, "nullable": true }, "givingEventKey": { "type": "string", "minLength": 1, "maxLength": 500, "nullable": true }, "processingFee": { "type": "number", "minimum": 0 }, "netAmount": { "type": "number", "minimum": 0 }, "paymentStatus": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ] }, "paymentLast4": { "type": "string", "maxLength": 4, "nullable": true }, "paymentBrand": { "type": "string", "maxLength": 100, "nullable": true }, "paymentMethodSub": { "type": "string", "maxLength": 100, "nullable": true }, "paymentMethodType": { "type": "string", "maxLength": 100, "nullable": true }, "paymentSource": { "type": "string", "maxLength": 100, "nullable": true }, "isRefunded": { "type": "boolean" }, "refundedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "sourceType": { "type": "string", "enum": [ "DIRECT", "DAF", "QCD_IRA", "MATCHING", "FOUNDATION", "ESTATE" ] }, "benefitDescription": { "type": "string", "nullable": true }, "benefitValue": { "type": "number", "minimum": 0, "nullable": true }, "deductibleAmount": { "type": "number", "minimum": 0, "nullable": true }, "stockTicker": { "type": "string", "nullable": true }, "stockShares": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "nullable": true }, "stockFmvPerShare": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "nullable": true }, "stockTransferDate": { "type": "string", "format": "date", "nullable": true }, "inKindDescription": { "type": "string", "nullable": true }, "inKindFmv": { "type": "number", "minimum": 0, "nullable": true }, "inKindAppraisalDate": { "type": "string", "format": "date", "nullable": true }, "foreignCurrency": { "type": "string", "nullable": true }, "foreignAmount": { "type": "number", "nullable": true }, "exchangeRate": { "type": "number", "nullable": true } } }, "UpdateContribution": { "type": "object", "additionalProperties": false, "description": "All fields are optional. Send null to clear a nullable field. Accounting-derived settlement and clearing fields are read-only.", "properties": { "donorId": { "type": "string", "minLength": 1, "nullable": true }, "sourceDonorId": { "type": "string", "minLength": 1, "nullable": true }, "amount": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "date": { "type": "string", "format": "date" }, "fundId": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "CASH", "CHECK", "CREDIT_CARD", "ACH", "ONLINE", "STOCK", "OTHER" ] }, "isTaxDeductible": { "type": "boolean" }, "checkNumber": { "type": "string", "nullable": true }, "checkDate": { "type": "string", "format": "date", "nullable": true }, "notes": { "type": "string", "nullable": true }, "memo": { "type": "string", "maxLength": 2000, "nullable": true }, "givingBatchId": { "type": "string", "minLength": 1, "nullable": true }, "settlementId": { "type": "string", "minLength": 1, "nullable": true }, "givingMerchantId": { "type": "string", "minLength": 1, "nullable": true }, "processingFee": { "type": "number", "minimum": 0, "nullable": true }, "netAmount": { "type": "number", "minimum": 0, "nullable": true }, "feeCovered": { "type": "boolean" }, "paymentStatus": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ] }, "paymentLast4": { "type": "string", "maxLength": 4, "nullable": true }, "paymentBrand": { "type": "string", "maxLength": 100, "nullable": true }, "paymentMethodSub": { "type": "string", "maxLength": 100, "nullable": true }, "paymentMethodType": { "type": "string", "maxLength": 100, "nullable": true }, "paymentSource": { "type": "string", "maxLength": 100, "nullable": true }, "isRefunded": { "type": "boolean" }, "refundedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "sourceType": { "type": "string", "nullable": true, "enum": [ "DIRECT", "DAF", "QCD_IRA", "MATCHING", "FOUNDATION", "ESTATE" ] }, "externalId": { "type": "string", "nullable": true }, "externalSource": { "type": "string", "enum": [ "PUSHPAY", "PLANNING_CENTER", "CCB", "TITHELY", "SUBSPLASH", "ROCK_RMS", "OVERFLOW", "MANUAL", "OTHER" ] }, "externalDonorId": { "type": "string", "maxLength": 500, "nullable": true }, "givingEventKey": { "type": "string", "minLength": 1, "maxLength": 500, "nullable": true }, "benefitDescription": { "type": "string", "nullable": true }, "benefitValue": { "type": "number", "minimum": 0, "nullable": true }, "deductibleAmount": { "type": "number", "minimum": 0, "nullable": true }, "stockTicker": { "type": "string", "nullable": true }, "stockShares": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "nullable": true }, "stockFmvPerShare": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "nullable": true }, "stockTransferDate": { "type": "string", "format": "date", "nullable": true }, "inKindDescription": { "type": "string", "nullable": true }, "inKindFmv": { "type": "number", "minimum": 0, "nullable": true }, "inKindAppraisalDate": { "type": "string", "format": "date", "nullable": true }, "foreignCurrency": { "type": "string", "nullable": true }, "foreignAmount": { "type": "number", "nullable": true }, "exchangeRate": { "type": "number", "nullable": true } } }, "ContributionListResponse": { "type": "object", "properties": { "contributions": { "type": "array", "items": { "$ref": "#/components/schemas/ContributionSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Settlement": { "type": "object", "description": "Recorded settlement values plus independently calculated linked-contribution totals. Accounting and bank-link state are read-only; raw provider metadata, sync diagnostics, accounting details, and fingerprints are excluded.", "required": [ "id", "provider", "externalId", "estimatedArrivalDate", "recordedTotals", "linkedContributionTotals", "currency", "status", "accounting", "bankLink", "isFrozen", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "STRIPE", "PUSHPAY", "SUBSPLASH", "TITHELY", "PLANNING_CENTER", "ROCK_RMS", "RAMP", "DIVVY", "OVERFLOW", "MANUAL" ] }, "externalId": { "type": "string" }, "externalReference": { "type": "string", "nullable": true }, "estimatedArrivalDate": { "type": "string", "format": "date-time", "description": "Calendar day represented as a UTC-midnight ISO timestamp." }, "actualArrivalDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Calendar day represented as a UTC-midnight ISO timestamp." }, "recordedTotals": { "$ref": "#/components/schemas/GivingTotals" }, "linkedContributionTotals": { "$ref": "#/components/schemas/GivingTotals" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "settlementType": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "IN_TRANSIT", "DEPOSITED", "MATCHED", "RECONCILED", "FAILED", "CANCELLED" ] }, "errorMessage": { "type": "string", "nullable": true }, "failureCode": { "type": "string", "nullable": true }, "depositBasis": { "type": "string", "nullable": true, "enum": [ "GROSS", "NET" ] }, "givingIntegration": { "$ref": "#/components/schemas/GivingIntegrationSummary", "nullable": true }, "merchant": { "$ref": "#/components/schemas/MerchantRelationshipSummary", "nullable": true }, "accounting": { "$ref": "#/components/schemas/SettlementAccountingSummary" }, "bankLink": { "$ref": "#/components/schemas/SettlementBankLinkSummary" }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionAssignment" } }, "batches": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementBatchSummary" } }, "isFrozen": { "type": "boolean", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SettlementSummary": { "type": "object", "description": "Compact settlement identity, lifecycle, recorded totals, linked-contribution totals, and accounting/bank-link state.", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "externalId": { "type": "string" }, "externalReference": { "type": "string", "nullable": true }, "estimatedArrivalDate": { "type": "string", "format": "date-time" }, "actualArrivalDate": { "type": "string", "format": "date-time", "nullable": true }, "recordedTotals": { "$ref": "#/components/schemas/GivingTotals" }, "linkedContributionTotals": { "$ref": "#/components/schemas/GivingTotals" }, "currency": { "type": "string" }, "settlementType": { "type": "string", "nullable": true }, "status": { "type": "string" }, "errorMessage": { "type": "string", "nullable": true }, "failureCode": { "type": "string", "nullable": true }, "depositBasis": { "type": "string", "nullable": true, "enum": [ "GROSS", "NET" ] }, "givingIntegration": { "$ref": "#/components/schemas/GivingIntegrationSummary", "nullable": true }, "merchant": { "$ref": "#/components/schemas/MerchantRelationshipSummary", "nullable": true }, "accounting": { "$ref": "#/components/schemas/SettlementAccountingSummary" }, "bankLink": { "$ref": "#/components/schemas/SettlementBankLinkSummary" }, "isFrozen": { "type": "boolean", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "GivingTotals": { "type": "object", "properties": { "gross": { "type": "number" }, "fees": { "type": "number" }, "net": { "type": "number" }, "paymentCount": { "type": "integer" }, "donationCount": { "type": "integer" } } }, "DimensionAssignment": { "type": "object", "additionalProperties": false, "required": [ "dimensionId", "dimensionValueId" ], "properties": { "dimensionId": { "type": "string" }, "dimensionName": { "type": "string", "nullable": true, "readOnly": true }, "dimensionValueId": { "type": "string" }, "dimensionValueName": { "type": "string", "nullable": true, "readOnly": true } } }, "DimensionInput": { "type": "object", "additionalProperties": false, "required": [ "dimensionId", "dimensionValueId" ], "properties": { "dimensionId": { "type": "string", "minLength": 1 }, "dimensionValueId": { "type": "string", "minLength": 1 } } }, "NamedResourceSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "DonorIdentitySummary": { "type": "object", "additionalProperties": false, "required": [ "id", "firstName", "lastName", "organizationName", "donorType" ], "properties": { "id": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "organizationName": { "type": "string", "nullable": true }, "donorType": { "type": "string", "nullable": true } } }, "FundRelationshipSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "fundType" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fundType": { "type": "string", "nullable": true } } }, "BatchRelationshipSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "externalReference", "batchDate", "status", "totalGross", "totalFees", "totalNet", "donationCount" ], "properties": { "id": { "type": "string" }, "externalReference": { "type": "string" }, "batchDate": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "totalGross": { "type": "number" }, "totalFees": { "type": "number" }, "totalNet": { "type": "number" }, "donationCount": { "type": "integer" } } }, "SettlementRelationshipSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "externalReference", "estimatedArrivalDate", "status", "totalNet" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "externalReference": { "type": "string", "nullable": true }, "estimatedArrivalDate": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "totalNet": { "type": "number" } } }, "BatchSettlementSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "externalReference", "status", "totalNet" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "externalReference": { "type": "string", "nullable": true }, "status": { "type": "string" }, "totalNet": { "type": "number" } } }, "JournalEntryRelationshipSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "entryNumber", "referenceNumber" ], "properties": { "id": { "type": "string" }, "entryNumber": { "type": "string", "nullable": true }, "referenceNumber": { "type": "string", "nullable": true } } }, "GivingIntegrationSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "name" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "MerchantRelationshipSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "campusId", "dimensionValueId" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campusId": { "type": "string", "nullable": true }, "dimensionValueId": { "type": "string", "nullable": true } } }, "ContributionMerchantSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "campus", "dimensionValue" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campus": { "$ref": "#/components/schemas/NamedResourceSummary", "nullable": true }, "dimensionValue": { "$ref": "#/components/schemas/NamedResourceSummary", "nullable": true } } }, "ContributionQuidProQuo": { "type": "object", "additionalProperties": false, "required": [ "benefitDescription", "benefitValue", "deductibleAmount" ], "properties": { "benefitDescription": { "type": "string", "nullable": true }, "benefitValue": { "type": "number", "nullable": true }, "deductibleAmount": { "type": "number", "nullable": true } } }, "ContributionStock": { "type": "object", "additionalProperties": false, "required": [ "ticker", "shares", "fairMarketValuePerShare", "transferDate" ], "properties": { "ticker": { "type": "string", "nullable": true }, "shares": { "type": "number", "nullable": true }, "fairMarketValuePerShare": { "type": "number", "nullable": true }, "transferDate": { "type": "string", "format": "date-time", "nullable": true } } }, "ContributionInKind": { "type": "object", "additionalProperties": false, "required": [ "description", "fairMarketValue", "appraisalDate" ], "properties": { "description": { "type": "string", "nullable": true }, "fairMarketValue": { "type": "number", "nullable": true }, "appraisalDate": { "type": "string", "format": "date-time", "nullable": true } } }, "SettlementAccountingSummary": { "type": "object", "additionalProperties": false, "readOnly": true, "required": [ "disposition", "reason", "journalEntry" ], "properties": { "disposition": { "type": "string", "enum": [ "ELIGIBLE", "NEEDS_REVIEW", "RECORDED_EXTERNALLY" ] }, "reason": { "type": "string", "nullable": true }, "journalEntry": { "$ref": "#/components/schemas/JournalEntryRelationshipSummary", "nullable": true } } }, "SettlementBankLinkSummary": { "type": "object", "additionalProperties": false, "readOnly": true, "required": [ "isLinked", "transaction" ], "properties": { "isLinked": { "type": "boolean" }, "transaction": { "type": "object", "nullable": true, "additionalProperties": false, "required": [ "id", "date", "amount", "description" ], "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "description": { "type": "string" } } } } }, "SettlementBatchSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "externalReference", "status", "batchDate", "totalNet" ], "properties": { "id": { "type": "string" }, "externalReference": { "type": "string" }, "status": { "type": "string" }, "batchDate": { "type": "string", "format": "date-time" }, "totalNet": { "type": "number" } } }, "FundSplit": { "type": "object", "additionalProperties": false, "required": [ "fundId", "fundName", "amount" ], "properties": { "fundId": { "type": "string" }, "fundName": { "type": "string", "nullable": true }, "amount": { "type": "number" } } }, "CreateSettlement": { "type": "object", "additionalProperties": false, "required": [ "estimatedArrivalDate", "totalGross", "totalFees", "totalNet", "paymentCount" ], "properties": { "provider": { "type": "string", "enum": [ "STRIPE", "PUSHPAY", "SUBSPLASH", "TITHELY", "PLANNING_CENTER", "ROCK_RMS", "RAMP", "DIVVY", "OVERFLOW", "MANUAL" ], "default": "MANUAL" }, "externalId": { "type": "string", "description": "Generated when omitted for a manual settlement." }, "externalReference": { "type": "string", "nullable": true }, "estimatedArrivalDate": { "type": "string", "format": "date" }, "actualArrivalDate": { "type": "string", "format": "date", "nullable": true }, "totalGross": { "type": "number", "minimum": 0 }, "totalFees": { "type": "number", "minimum": 0 }, "totalNet": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "USD" }, "paymentCount": { "type": "integer", "minimum": 0 }, "settlementType": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "IN_TRANSIT", "DEPOSITED", "FAILED", "CANCELLED" ] }, "errorMessage": { "type": "string", "nullable": true }, "failureCode": { "type": "string", "nullable": true }, "depositBasis": { "type": "string", "nullable": true, "enum": [ "GROSS", "NET" ] }, "givingIntegrationId": { "type": "string", "nullable": true }, "givingMerchantId": { "type": "string", "nullable": true }, "contributionIds": { "type": "array", "maxItems": 10000, "items": { "type": "string" } }, "givingBatchIds": { "type": "array", "maxItems": 10000, "items": { "type": "string" } }, "dimensions": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DimensionInput" } } } }, "UpdateSettlement": { "type": "object", "additionalProperties": false, "description": "All fields are optional; null clears nullable fields. MATCHED and RECONCILED are read-only accounting states.", "properties": { "provider": { "type": "string", "enum": [ "STRIPE", "PUSHPAY", "SUBSPLASH", "TITHELY", "PLANNING_CENTER", "ROCK_RMS", "RAMP", "DIVVY", "OVERFLOW", "MANUAL" ] }, "externalId": { "type": "string" }, "externalReference": { "type": "string", "nullable": true }, "estimatedArrivalDate": { "type": "string", "format": "date" }, "actualArrivalDate": { "type": "string", "format": "date", "nullable": true }, "totalGross": { "type": "number", "minimum": 0 }, "totalFees": { "type": "number", "minimum": 0 }, "totalNet": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "paymentCount": { "type": "integer", "minimum": 0 }, "settlementType": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "IN_TRANSIT", "DEPOSITED", "FAILED", "CANCELLED" ] }, "errorMessage": { "type": "string", "nullable": true }, "failureCode": { "type": "string", "nullable": true }, "depositBasis": { "type": "string", "nullable": true, "enum": [ "GROSS", "NET" ] }, "givingIntegrationId": { "type": "string", "nullable": true }, "givingMerchantId": { "type": "string", "nullable": true }, "contributionIds": { "type": "array", "maxItems": 10000, "items": { "type": "string" } }, "givingBatchIds": { "type": "array", "maxItems": 10000, "items": { "type": "string" } }, "dimensions": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DimensionInput" } } } }, "SettlementListResponse": { "type": "object", "properties": { "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "GivingBatch": { "type": "object", "description": "Giving batch whose totals and donation count are derived from current contribution membership. Metadata and sync diagnostics are excluded.", "properties": { "id": { "type": "string" }, "externalBatchId": { "type": "string" }, "externalReference": { "type": "string" }, "batchDate": { "type": "string", "format": "date-time", "description": "Calendar day represented as a UTC-midnight ISO timestamp." }, "totals": { "$ref": "#/components/schemas/GivingTotals" }, "status": { "type": "string", "enum": [ "OPEN", "COMMITTED", "SETTLED", "FAILED" ] }, "isCommitted": { "type": "boolean" }, "committedAt": { "type": "string", "format": "date-time", "nullable": true }, "processedAt": { "type": "string", "format": "date-time", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "givingIntegration": { "$ref": "#/components/schemas/GivingIntegrationSummary", "nullable": true }, "merchant": { "$ref": "#/components/schemas/MerchantRelationshipSummary", "nullable": true }, "settlement": { "$ref": "#/components/schemas/BatchSettlementSummary", "nullable": true }, "journalEntry": { "$ref": "#/components/schemas/JournalEntryRelationshipSummary", "nullable": true, "readOnly": true }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionAssignment" } }, "fundSplits": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/FundSplit" } }, "contributionIds": { "type": "array", "items": { "type": "string" } }, "isFrozen": { "type": "boolean", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "GivingBatchSummary": { "type": "object", "description": "Compact giving batch identity, calendar date, derived totals, lifecycle, and linked settlement summary.", "properties": { "id": { "type": "string" }, "externalBatchId": { "type": "string" }, "externalReference": { "type": "string" }, "batchDate": { "type": "string", "format": "date-time" }, "totals": { "$ref": "#/components/schemas/GivingTotals" }, "status": { "type": "string" }, "isCommitted": { "type": "boolean" }, "committedAt": { "type": "string", "format": "date-time", "nullable": true }, "processedAt": { "type": "string", "format": "date-time", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "givingIntegration": { "$ref": "#/components/schemas/GivingIntegrationSummary", "nullable": true }, "merchant": { "$ref": "#/components/schemas/MerchantRelationshipSummary", "nullable": true }, "settlement": { "$ref": "#/components/schemas/BatchSettlementSummary", "nullable": true }, "journalEntry": { "$ref": "#/components/schemas/JournalEntryRelationshipSummary", "nullable": true, "readOnly": true }, "isFrozen": { "type": "boolean", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateGivingBatch": { "type": "object", "additionalProperties": false, "required": [ "externalReference", "batchDate" ], "properties": { "externalBatchId": { "type": "string", "description": "Generated when omitted." }, "externalReference": { "type": "string", "minLength": 1 }, "batchDate": { "type": "string", "format": "date" }, "givingIntegrationId": { "type": "string", "nullable": true, "description": "When omitted, Grain's non-syncing manual giving integration is used." }, "givingMerchantId": { "type": "string", "nullable": true }, "settlementId": { "type": "string", "nullable": true }, "contributionIds": { "type": "array", "maxItems": 10000, "items": { "type": "string" } }, "dimensions": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DimensionInput" } }, "status": { "type": "string", "enum": [ "OPEN", "COMMITTED", "FAILED" ] }, "errorMessage": { "type": "string", "nullable": true } } }, "UpdateGivingBatch": { "type": "object", "additionalProperties": false, "description": "All fields are optional; null clears nullable fields. SETTLED is read-only.", "properties": { "externalBatchId": { "type": "string" }, "externalReference": { "type": "string" }, "batchDate": { "type": "string", "format": "date" }, "givingIntegrationId": { "type": "string" }, "givingMerchantId": { "type": "string", "nullable": true }, "settlementId": { "type": "string", "nullable": true }, "contributionIds": { "type": "array", "maxItems": 10000, "items": { "type": "string" } }, "dimensions": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DimensionInput" } }, "status": { "type": "string", "enum": [ "OPEN", "COMMITTED", "FAILED" ] }, "errorMessage": { "type": "string", "nullable": true } } }, "GivingBatchListResponse": { "type": "object", "properties": { "batches": { "type": "array", "items": { "$ref": "#/components/schemas/GivingBatchSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Pledge": { "type": "object", "properties": { "id": { "type": "string" }, "donorId": { "type": "string" }, "fundId": { "type": "string" }, "campaignId": { "type": "string", "nullable": true }, "totalAmount": { "type": "number" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "CANCELLED" ] } } }, "CreatePledge": { "type": "object", "required": [ "donorId", "fundId", "totalAmount", "startDate" ], "properties": { "donorId": { "type": "string", "example": "cm456def789ghi" }, "fundId": { "type": "string", "example": "cm789ghi012jkl" }, "campaignId": { "type": "string" }, "totalAmount": { "type": "number", "example": 12000 }, "startDate": { "type": "string", "format": "date", "example": "2026-01-01" }, "endDate": { "type": "string", "format": "date", "example": "2026-12-31" }, "notes": { "type": "string" } } }, "PledgeListResponse": { "type": "object", "properties": { "pledges": { "type": "array", "items": { "$ref": "#/components/schemas/Pledge" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "PledgeCardInput": { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 128, "example": "card-1001" }, "rockPersonId": { "type": "string", "maxLength": 128, "description": "Current Rock Person.Id. Exact identity routing bypasses fuzzy donor matching." }, "donorFirstName": { "type": "string", "maxLength": 100, "example": "Sarah" }, "donorLastName": { "type": "string", "maxLength": 100, "example": "Johnson" }, "donorEmail": { "type": "string", "format": "email", "maxLength": 255, "example": "sarah@example.org" }, "donorPhone": { "type": "string", "maxLength": 50, "example": "+1 615 555 0100" }, "donorAddress": { "type": "string", "maxLength": 255, "example": "100 Church Street" }, "donorAddress2": { "type": "string", "maxLength": 255, "example": "Suite 200", "description": "Second street-address line. Grain joins both lines with one space for donor matching while preserving both in the import artifact." }, "donorCity": { "type": "string", "maxLength": 100, "example": "Nashville" }, "donorState": { "type": "string", "maxLength": 100, "example": "TN" }, "donorZip": { "type": "string", "maxLength": 20, "example": "37201" }, "amount": { "type": "number", "minimum": 0, "example": 12000 }, "frequency": { "type": "string", "enum": [ "ONE_TIME", "WEEKLY", "BIWEEKLY", "MONTHLY", "QUARTERLY", "ANNUALLY" ], "example": "MONTHLY" }, "fundId": { "type": "string", "description": "Optional per-card Grain fund ID. Do not send with rockAccountId." }, "rockAccountId": { "type": "string", "maxLength": 128, "description": "Exact Rock financial account ID for this card. Do not send with fundId." }, "fundName": { "type": "string", "maxLength": 200, "description": "Informational label shown during review. It is never used for fund routing or fallback." }, "campusId": { "type": "string", "deprecated": true, "description": "Legacy internal Grain campus ID. Do not send with rockCampusId." }, "rockCampusId": { "type": "string", "maxLength": 128, "description": "Exact Rock campus ID resolved through the integration campus catalog. Campus does not select a financial account." }, "campusName": { "type": "string", "maxLength": 200, "description": "Legacy campus label used by the existing review matcher. Use rockCampusId for exact routing." }, "startDate": { "type": "string", "format": "date", "example": "2027-01-01" }, "endDate": { "type": "string", "format": "date", "example": "2027-12-31" }, "notes": { "type": "string", "maxLength": 2000 } } }, "CreatePledgeCardImport": { "type": "object", "required": [ "cards" ], "properties": { "scanGroupId": { "type": "string", "description": "Existing pledge card scan group ID. When set, cards are added as a new batch in that group. campaignId is inherited; a supplied request default fund or Rock account overrides the group's default." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "2027 annual pledge cards", "description": "Required when scanGroupId is omitted. Becomes the new scan group name." }, "defaultFundId": { "type": "string", "description": "Grain fund used when a card has no override. Required when scanGroupId is omitted unless defaultRockAccountId is supplied." }, "defaultRockAccountId": { "type": "string", "description": "Exact Rock financial account used when a card has no override. Do not send with defaultFundId." }, "campaignId": { "type": "string", "description": "Optional Grain pledge campaign ID. Ignored when scanGroupId is set; the group's campaign is used instead." }, "pledgeAudience": { "type": "string", "enum": [ "ADULT", "STUDENT" ], "default": "ADULT" }, "cards": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/PledgeCardInput" } } } }, "PledgeCardImportResult": { "type": "object", "required": [ "scanGroupId", "batchId", "reviewUrl", "idempotentReplay", "sourceFileAttachmentId", "cardsImported", "cardsSkipped", "cardsWithIssues", "duplicateCards", "items" ], "properties": { "scanGroupId": { "type": "string" }, "batchId": { "type": "string" }, "reviewUrl": { "type": "string", "format": "uri" }, "idempotentReplay": { "type": "boolean" }, "sourceFileAttachmentId": { "type": "string", "description": "Secured audit artifact ID; not a scanned card attachment" }, "cardsImported": { "type": "integer", "minimum": 0 }, "cardsSkipped": { "type": "integer", "minimum": 0 }, "cardsWithIssues": { "type": "integer", "minimum": 0 }, "duplicateCards": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "rockPersonId": { "type": "string", "nullable": true }, "rockAccountId": { "type": "string", "nullable": true }, "sourceIdentityStatus": { "type": "string", "nullable": true, "enum": [ "PENDING", "MATCHED", "CONFLICT", "NOT_FOUND" ] }, "status": { "type": "string", "enum": [ "EXTRACTED", "SKIPPED" ] }, "issue": { "type": "string", "nullable": true }, "duplicateOfId": { "type": "string", "nullable": true } } } } } }, "PledgeCardImportReferenceData": { "type": "object", "required": [ "hasRockIntegration", "scanGroups", "campaigns", "funds", "rockCampuses", "rockAccounts" ], "properties": { "hasRockIntegration": { "type": "boolean", "description": "Whether the organization has an active Rock RMS integration." }, "scanGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": "string", "nullable": true }, "defaultFundId": { "type": "string" }, "defaultSourceProvider": { "type": "string", "nullable": true }, "defaultSourceExternalFundId": { "type": "string", "nullable": true } } } }, "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "fundId": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "nullable": true } } } }, "funds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fundType": { "type": "string" } } } }, "rockCampuses": { "type": "array", "items": { "type": "object", "properties": { "rockCampusId": { "type": "string" }, "grainCampusId": { "type": "string" }, "name": { "type": "string" }, "shortCode": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" } } } }, "rockAccounts": { "type": "array", "items": { "type": "object", "properties": { "rockAccountId": { "type": "string" }, "parentRockAccountId": { "type": "string", "nullable": true }, "name": { "type": "string" }, "path": { "type": "string" }, "isActive": { "type": "boolean" }, "isMapped": { "type": "boolean" }, "mappingState": { "type": "string", "enum": [ "MAPPED", "UNMAPPED", "INACTIVE_FUND", "AMBIGUOUS", "NOT_CATALOGED" ] }, "grainFundId": { "type": "string", "nullable": true }, "grainFundName": { "type": "string", "nullable": true } } } } } }, "Household": { "type": "object", "description": "Household detail with a compact member collection, normalized external IDs, primary contact, and live giving aggregates.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "primaryContactId": { "type": "string", "nullable": true }, "primaryContact": { "$ref": "#/components/schemas/DonorSummary", "nullable": true }, "externalIds": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/DonorSummary" } }, "aggregates": { "type": "object", "properties": { "memberCount": { "type": "integer" }, "lifetimeGiving": { "type": "number" }, "lastGiftDate": { "type": "string", "format": "date-time", "nullable": true } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "HouseholdSummary": { "type": "object", "description": "Compact household identity, primary contact, normalized external IDs, and member/giving aggregates.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "primaryContactId": { "type": "string", "nullable": true }, "primaryContact": { "$ref": "#/components/schemas/DonorSummary", "nullable": true }, "externalIds": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" } }, "aggregates": { "type": "object", "properties": { "memberCount": { "type": "integer" }, "lifetimeGiving": { "type": "number" }, "lastGiftDate": { "type": "string", "format": "date-time", "nullable": true } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateHousehold": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Johnson Family" }, "primaryContactId": { "type": "string", "nullable": true, "example": "cm456def789ghi" }, "externalIds": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } } }, "UpdateHousehold": { "type": "object", "additionalProperties": false, "description": "All fields are optional; null clears primaryContactId or externalIds.", "properties": { "name": { "type": "string", "minLength": 1 }, "primaryContactId": { "type": "string", "nullable": true }, "externalIds": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } } }, "HouseholdMemberWrite": { "type": "object", "additionalProperties": false, "required": [ "donorId" ], "properties": { "donorId": { "type": "string" }, "position": { "type": "string", "nullable": true, "enum": [ "PRIMARY", "SPOUSE", "CHILD", "OTHER" ] }, "isPrimaryContact": { "type": "boolean" } } }, "UpdateHouseholdMember": { "type": "object", "additionalProperties": false, "properties": { "position": { "type": "string", "nullable": true, "enum": [ "PRIMARY", "SPOUSE", "CHILD", "OTHER" ] }, "isPrimaryContact": { "type": "boolean" } } }, "HouseholdListResponse": { "type": "object", "properties": { "households": { "type": "array", "items": { "$ref": "#/components/schemas/HouseholdSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "examples": { "TransactionListExample": { "value": { "transactions": [ { "id": "cm111aaa222bbb", "externalId": null, "description": "Office Depot", "amount": 184.32, "direction": "OUTFLOW", "transactionType": "WITHDRAWAL", "date": "2026-07-01T00:00:00.000Z", "referenceNumber": null, "source": "PLAID", "reviewStatus": "AUTO_CATEGORIZED", "isReconciled": false, "is1099Excluded": false, "bankAccount": { "id": "cm333ccc444ddd", "name": "Operating Checking", "mask": "4821", "accountType": "depository" }, "sourceAccount": { "id": "cm555eee666fff", "accountNumber": "1010", "name": "Operating Checking", "accountType": "ASSET" }, "fund": { "id": "cm789ghi012jkl", "name": "General Fund", "fundType": "UNRESTRICTED" }, "vendor": { "id": "cm777ggg888hhh", "name": "Office Depot" }, "dimensions": [ { "dimensionId": "cm999iii000jjj", "dimensionName": "Department", "dimensionValueId": "cm121kkk232lll", "dimensionValueName": "Administration" } ], "coding": { "status": "CATEGORIZED", "journalEntryId": "cm343mmm454nnn", "entryNumber": "JE-1042", "isSplit": false, "lines": [ { "id": "cm565ooo676ppp", "account": { "id": "cm787qqq898rrr", "accountNumber": "6100", "name": "Office Supplies", "accountType": "EXPENSE" }, "fund": { "id": "cm789ghi012jkl", "name": "General Fund", "fundType": "UNRESTRICTED" }, "amount": 184.32, "memo": null, "dimensions": [ { "dimensionId": "cm999iii000jjj", "dimensionName": "Department", "dimensionValueId": "cm121kkk232lll", "dimensionValueName": "Administration" } ] } ], "missingRequiredDimensions": [] }, "suggestion": null, "attachmentCount": 1, "canManage": true, "createdAt": "2026-07-02T14:03:11.000Z", "updatedAt": "2026-07-02T14:05:40.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 58, "totalPages": 3 } } }, "BillListExample": { "value": { "bills": [ { "id": "cm222bbb333ccc", "billNumber": "INV-1042", "billDate": "2026-06-15T00:00:00.000Z", "dueDate": "2026-07-15T00:00:00.000Z", "amount": 850, "postingMode": "STANDARD", "paidAmount": 0, "creditedAmount": 0, "remainingAmount": 850, "status": "PENDING" } ], "pagination": { "page": 1, "limit": 20, "total": 12, "totalPages": 1 } } }, "DonorListExample": { "value": { "donors": [ { "id": "cm456def789ghi", "firstName": "Sarah", "lastName": "Johnson", "email": "sarah@gracechurch.org", "donorType": "INDIVIDUAL" } ], "pagination": { "page": 1, "limit": 20, "total": 142, "totalPages": 8 } } }, "ContributionListExample": { "value": { "contributions": [ { "id": "cm333ccc444ddd", "donorId": "cm456def789ghi", "amount": 250, "date": "2026-07-06T00:00:00.000Z", "fundId": "cm789ghi012jkl", "method": "CHECK", "isTaxDeductible": true, "externalSource": "MANUAL" } ], "pagination": { "page": 1, "limit": 20, "total": 890, "totalPages": 45 } } }, "SettlementListExample": { "value": { "settlements": [ { "id": "settlement_1", "provider": "MANUAL", "externalId": "api-example", "externalReference": "August online giving", "estimatedArrivalDate": "2026-08-21T00:00:00.000Z", "actualArrivalDate": null, "recordedTotals": { "gross": 1025, "fees": 25, "net": 1000, "paymentCount": 8 }, "linkedContributionTotals": { "gross": 1025, "fees": 25, "net": 1000, "paymentCount": 8 }, "currency": "USD", "settlementType": null, "status": "PENDING", "accounting": { "disposition": "ELIGIBLE", "reason": null, "journalEntry": null }, "bankLink": { "isLinked": false, "transaction": null }, "dimensions": [], "batches": [], "isFrozen": false, "createdAt": "2026-08-21T12:00:00.000Z", "updatedAt": "2026-08-21T12:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } }, "GivingBatchListExample": { "value": { "batches": [ { "id": "batch_1", "externalBatchId": "api-example", "externalReference": "Sunday online gifts", "batchDate": "2026-08-16T00:00:00.000Z", "totals": { "gross": 1025, "fees": 25, "net": 1000, "donationCount": 8 }, "status": "OPEN", "isCommitted": false, "committedAt": null, "processedAt": null, "dimensions": [], "fundSplits": [ { "fundId": "fund_1", "fundName": "General", "amount": 1025 } ], "contributionIds": [ "contribution_1" ], "isFrozen": false, "createdAt": "2026-08-16T12:00:00.000Z", "updatedAt": "2026-08-16T12:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } }, "PledgeListExample": { "value": { "pledges": [ { "id": "cm444ddd555eee", "donorId": "cm456def789ghi", "fundId": "cm789ghi012jkl", "totalAmount": 12000, "startDate": "2026-01-01T00:00:00.000Z", "endDate": "2026-12-31T00:00:00.000Z", "status": "ACTIVE" } ], "pagination": { "page": 1, "limit": 20, "total": 34, "totalPages": 2 } } }, "HouseholdListExample": { "value": { "households": [ { "id": "cm555eee666fff", "name": "Johnson Family", "primaryContactId": "cm456def789ghi" } ], "pagination": { "page": 1, "limit": 20, "total": 67, "totalPages": 4 } } } } }, "paths": { "/api/v1/funds": { "get": { "tags": [ "Funds" ], "operationId": "listFunds", "summary": "List funds", "description": "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 organization API keys and Grain-managed OAuth apps; OAuth users must also have permission to view funds. Existing keys and OAuth grants must explicitly include the new scope.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Fund IDs and names available for mapping", "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundListResponse" }, "example": { "funds": [ { "id": "cm789ghi012jkl", "name": "General Fund" } ] } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/accounts": { "get": { "tags": [ "Coding Reference Data" ], "operationId": "listAccounts", "summary": "List accounts", "description": "Returns active postable chart-of-accounts entries ordered by account number. Summary accounts are excluded. Not paginated. Requires accounts:read.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "name": "accountType", "in": "query", "schema": { "type": "string", "enum": [ "ASSET", "LIABILITY", "NET_ASSET", "REVENUE", "EXPENSE" ] } }, { "name": "isCashAccount", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Postable accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountListResponse" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/dimensions": { "get": { "tags": [ "Coding Reference Data" ], "operationId": "listDimensions", "summary": "List dimensions", "description": "Returns active dimensions (such as Department, Location, or Project) with their active values. Not paginated. Requires accounts:read.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Active dimensions and values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionListResponse" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/vendors": { "get": { "tags": [ "Coding Reference Data" ], "operationId": "listVendors", "summary": "List vendors", "description": "Returns active vendors ordered by name. Not paginated. Requires vendors:read.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Active vendors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorListResponse" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List authorized organizations", "description": "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.", "security": [ { "GrainOAuth2": [ "openid" ] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Organizations this application may access for the signed-in user", "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizations" ], "properties": { "organizations": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } }, "examples": { "default": { "value": { "organizations": [ { "id": "cm123abc456def", "name": "First Church" } ] } } } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions": { "get": { "tags": [ "Transactions" ], "operationId": "listTransactions", "summary": "List transactions", "description": "Returns bank, card, and manual transactions with their coding. Comma-separated ID filters match any listed ID.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Transactions per page" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Matches description, reference number, or amount." }, { "name": "transactionType", "in": "query", "schema": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAWAL", "TRANSFER", "ADJUSTMENT" ] } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "isReconciled", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "isCategorized", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "true returns transactions with a journal entry; false returns uncategorized transactions." }, { "name": "hasAttachments", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "reviewStatus", "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "PENDING_REVIEW", "AUTO_CATEGORIZED", "APPROVED", "POSTED", "REJECTED" ] } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "PLAID", "RAMP", "MANUAL", "IMPORT" ] } }, { "name": "externalId", "in": "query", "schema": { "type": "string" }, "description": "Find the transaction created with this externalId." }, { "name": "amountMin", "in": "query", "schema": { "type": "number" } }, { "name": "amountMax", "in": "query", "schema": { "type": "number" } }, { "name": "fundIds", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated fund IDs." }, { "name": "vendorIds", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated vendor IDs." }, { "name": "accountIds", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated category account IDs." }, { "name": "bankAccountIds", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated bank or card feed account IDs." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "date", "amount", "description", "createdAt" ], "default": "date" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListResponse" }, "examples": { "default": { "$ref": "#/components/examples/TransactionListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Transactions" ], "operationId": "createTransaction", "summary": "Create transaction", "description": "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 PUT /transactions/{id}/coding.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable key for one transaction create, retained for the lifetime of the organization. Keys are scoped to organization and credential.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransaction" }, "examples": { "deposit": { "value": { "description": "Weekly offering deposit", "amount": 4250, "date": "2026-07-01", "transactionType": "DEPOSIT", "referenceNumber": "DEP-2026-0701" } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}": { "get": { "tags": [ "Transactions" ], "operationId": "getTransaction", "summary": "Get transaction by ID", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Transactions" ], "operationId": "updateTransaction", "summary": "Update transaction", "description": "Description, reference number, and date changes are copied to the linked journal entry. Changing the vendor re-attributes the journal entry.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTransaction" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Transactions" ], "operationId": "deleteTransaction", "summary": "Delete transaction", "description": "Reconciled transactions cannot be deleted.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}/coding": { "put": { "tags": [ "Transactions" ], "operationId": "setTransactionCoding", "summary": "Code or split a transaction", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTransactionCoding" }, "examples": { "single": { "value": { "lines": [ { "accountId": "cm787qqq898rrr", "amount": 184.32 } ] } }, "split": { "value": { "defaultFundId": "cm789ghi012jkl", "lines": [ { "accountId": "cm787qqq898rrr", "amount": 120, "dimensions": [ { "dimensionId": "cm999iii000jjj", "dimensionValueId": "cm121kkk232lll" } ] }, { "accountId": "cm909sss010ttt", "amount": 64.32, "memo": "Coffee for volunteers" } ] } } } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Coded transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Transactions" ], "operationId": "clearTransactionCoding", "summary": "Uncategorize a transaction", "description": "Deletes the transaction's draft journal entry and returns it to review. Approved transactions return 409; unapprove them first. Reconciled transactions cannot be uncategorized.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Uncategorized transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}/dimensions": { "put": { "tags": [ "Transactions" ], "operationId": "setTransactionDimensions", "summary": "Set transaction dimensions", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTransactionDimensions" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Transaction with updated dimensions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}/approve": { "post": { "tags": [ "Transactions" ], "operationId": "approveTransaction", "summary": "Approve a transaction", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Approved transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}/unapprove": { "post": { "tags": [ "Transactions" ], "operationId": "unapproveTransaction", "summary": "Unapprove a transaction", "description": "Returns a posted journal entry to draft so it can be recoded. Requires the transactions:approve scope. Safe to retry.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unapproved transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}/attachments": { "get": { "tags": [ "Transactions" ], "operationId": "listTransactionAttachments", "summary": "List transaction attachments", "description": "Returns receipts and other documents attached to the transaction, newest first.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Attachments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionAttachmentListResponse" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Transactions" ], "operationId": "uploadTransactionAttachment", "summary": "Upload a receipt", "description": "Attaches a PDF or image (JPEG, PNG, GIF, WebP, or HEIC) of up to 5 MB. Requires transactions:write.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "description": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Uploaded attachment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionAttachment" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Attachment larger than 5 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}/attachments/{fileId}/download": { "get": { "tags": [ "Transactions" ], "operationId": "getTransactionAttachmentDownload", "summary": "Get an attachment download URL", "description": "Returns a signed URL that expires after 15 minutes.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Signed download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentDownload" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/transactions/{id}/attachments/{fileId}": { "delete": { "tags": [ "Transactions" ], "operationId": "deleteTransactionAttachment", "summary": "Delete an attachment", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" }, { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/bills": { "get": { "tags": [ "Bills" ], "summary": "List bills", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "statusGroup", "in": "query", "schema": { "type": "string", "enum": [ "open", "dueSoon", "overdue" ] } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "dueDate", "amount", "billNumber", "billDate", "vendorName", "fundName", "status", "createdAt" ], "default": "dueDate" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated bills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillListResponse" }, "examples": { "default": { "$ref": "#/components/examples/BillListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Bills" ], "summary": "Create bill", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBill" }, "examples": { "invoice": { "value": { "billNumber": "INV-1042", "billDate": "2026-06-15", "dueDate": "2026-07-15", "amount": 850, "notes": "HVAC maintenance contract" } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created bill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/bills/{id}": { "get": { "tags": [ "Bills" ], "summary": "Get bill", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Bills" ], "summary": "Update bill", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBill" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated bill", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Bills" ], "summary": "Delete bill", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/donors": { "get": { "tags": [ "Donors" ], "summary": "List donors", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "householdRef", "in": "query", "schema": { "type": "string" } }, { "name": "isActive", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "hasGiven", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "lastGiftFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "lastGiftTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "states", "in": "query", "description": "Comma-separated state values.", "schema": { "type": "string" } }, { "name": "cities", "in": "query", "description": "Comma-separated city values.", "schema": { "type": "string" } }, { "name": "zipCodes", "in": "query", "description": "Comma-separated postal codes.", "schema": { "type": "string" } }, { "name": "membershipStatuses", "in": "query", "description": "Comma-separated membership statuses.", "schema": { "type": "string" } }, { "name": "donorTypes", "in": "query", "description": "Comma-separated donor types.", "schema": { "type": "string" } }, { "name": "givingAmountMin", "in": "query", "schema": { "type": "number" } }, { "name": "givingAmountMax", "in": "query", "schema": { "type": "number" } }, { "name": "hasEmail", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "hasPhone", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "name", "totalGiving", "createdAt" ], "default": "name" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated donors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DonorListResponse" }, "examples": { "default": { "$ref": "#/components/examples/DonorListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Donors" ], "summary": "Create donor", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDonor" }, "examples": { "individual": { "value": { "firstName": "Sarah", "lastName": "Johnson", "email": "sarah@gracechurch.org", "phone": "+15551234567" } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created donor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Donor" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/donors/{id}": { "get": { "tags": [ "Donors" ], "summary": "Get donor", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Donor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Donor" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Donors" ], "summary": "Update donor", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDonor" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated donor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Donor" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Donors" ], "summary": "Delete donor", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/contributions": { "get": { "tags": [ "Contributions" ], "summary": "List contributions", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "donorId", "in": "query", "schema": { "type": "string" } }, { "name": "fundId", "in": "query", "schema": { "type": "string" } }, { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "CASH", "CHECK", "CREDIT_CARD", "ACH", "ONLINE", "STOCK", "OTHER" ] } }, { "name": "givingBatchId", "in": "query", "schema": { "type": "string" } }, { "name": "settlementId", "in": "query", "schema": { "type": "string" } }, { "name": "givingMerchantId", "in": "query", "schema": { "type": "string" } }, { "name": "paymentStatus", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ] } }, { "name": "isRefunded", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "sourceType", "in": "query", "schema": { "type": "string", "enum": [ "DIRECT", "DAF", "QCD_IRA", "MATCHING", "FOUNDATION", "ESTATE" ] } }, { "name": "sourceDonorId", "in": "query", "schema": { "type": "string" } }, { "name": "isSettled", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "isCleared", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "hasDonor", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "externalSource", "in": "query", "schema": { "type": "string", "enum": [ "PUSHPAY", "PLANNING_CENTER", "CCB", "TITHELY", "SUBSPLASH", "ROCK_RMS", "OVERFLOW", "MANUAL", "OTHER" ] } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "date", "amount", "donor", "createdAt" ], "default": "date" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated contributions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContributionListResponse" }, "examples": { "default": { "$ref": "#/components/examples/ContributionListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Contributions" ], "summary": "Create contribution", "description": "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 split gifts.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable key for one contribution create, retained for the lifetime of the organization. Use a distinct key per split row. Replays return the current representation with current permissions; they do not restore an earlier snapshot.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContribution" }, "examples": { "check": { "value": { "donorId": "cm456def789ghi", "amount": 250, "date": "2026-07-06", "fundId": "cm789ghi012jkl", "method": "CHECK", "checkNumber": "1042" } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created contribution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contribution" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/contributions/{id}": { "get": { "tags": [ "Contributions" ], "summary": "Get contribution", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Contribution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contribution" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Contributions" ], "summary": "Update contribution", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContribution" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated contribution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contribution" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Contributions" ], "summary": "Delete contribution", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/settlements": { "get": { "tags": [ "Settlements" ], "summary": "List settlements", "description": "Returns recorded totals and independently calculated totals from linked contributions. dateFrom/dateTo filter the UTC calendar arrival day; dateTo is inclusive to callers.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/GivingLimit" }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "STRIPE", "PUSHPAY", "SUBSPLASH", "TITHELY", "PLANNING_CENTER", "ROCK_RMS", "RAMP", "DIVVY", "OVERFLOW", "MANUAL" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "IN_TRANSIT", "DEPOSITED", "MATCHED", "RECONCILED", "FAILED", "CANCELLED" ] } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "givingIntegrationId", "in": "query", "schema": { "type": "string" } }, { "name": "givingMerchantId", "in": "query", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "estimatedArrivalDate", "totalGross", "totalNet", "createdAt" ], "default": "estimatedArrivalDate" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated settlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementListResponse" }, "examples": { "default": { "$ref": "#/components/examples/SettlementListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Settlements" ], "summary": "Create settlement", "description": "Creates a resource record only. It never posts a journal entry, links a bank transaction, or reconciles accounting. contributionIds and givingBatchIds are applied atomically.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSettlement" }, "example": { "externalReference": "August online giving", "estimatedArrivalDate": "2026-08-21", "totalGross": 1025, "totalFees": 25, "totalNet": 1000, "paymentCount": 8, "contributionIds": [ "contribution_1" ] } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/settlements/{id}": { "get": { "tags": [ "Settlements" ], "summary": "Get settlement", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Settlements" ], "summary": "Update settlement", "description": "All relationship writes are tenant-scoped and atomic. Accounting-frozen settlements return 409.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettlement" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Settlements" ], "summary": "Delete settlement", "description": "Unlinks and preserves contributions and giving batches. Accounting-frozen resources return 409.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/batches": { "get": { "tags": [ "Giving Batches" ], "summary": "List giving batches", "description": "Returns giving batches, not pledge-card review batches. Totals are derived from current contribution membership.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/GivingLimit" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "OPEN", "COMMITTED", "SETTLED", "FAILED" ] } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "givingIntegrationId", "in": "query", "schema": { "type": "string" } }, { "name": "givingMerchantId", "in": "query", "schema": { "type": "string" } }, { "name": "settlementId", "in": "query", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "batchDate", "totalGross", "totalNet", "createdAt" ], "default": "batchDate" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated giving batches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GivingBatchListResponse" }, "examples": { "default": { "$ref": "#/components/examples/GivingBatchListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Giving Batches" ], "summary": "Create giving batch", "description": "Creates an empty or populated batch without posting accounting. contributionIds atomically replace membership.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGivingBatch" }, "example": { "externalReference": "Sunday online gifts", "batchDate": "2026-08-16", "contributionIds": [ "contribution_1" ] } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created giving batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GivingBatch" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/batches/{id}": { "get": { "tags": [ "Giving Batches" ], "summary": "Get giving batch", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Giving batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GivingBatch" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Giving Batches" ], "summary": "Update giving batch", "description": "Recalculates totals after amount, fee, or membership changes. SETTLED is an accounting-owned state and cannot be set here.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGivingBatch" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated giving batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GivingBatch" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Giving Batches" ], "summary": "Delete giving batch", "description": "Unlinks and preserves contributions. Accounting-frozen resources return 409.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/pledge-card-imports": { "post": { "tags": [ "Pledge Card Imports" ], "summary": "Import pledge card data for review", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePledgeCardImport" }, "examples": { "annualCampaign": { "value": { "scanGroupId": "CMRC90", "defaultRockAccountId": "101", "cards": [ { "externalId": "882145", "rockPersonId": "34567", "rockAccountId": "204", "rockCampusId": "3", "donorFirstName": "Sarah", "donorLastName": "Johnson", "donorEmail": "sarah@example.org", "amount": 12000, "frequency": "MONTHLY", "startDate": "2027-01-01", "endDate": "2027-12-31" } ] } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Pledge card data imported for review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PledgeCardImportResult" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 2 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/pledge-card-imports/reference-data": { "get": { "tags": [ "Pledge Card Imports" ], "summary": "List pledge card import reference data", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Pledge card import reference data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PledgeCardImportReferenceData" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/pledges": { "get": { "tags": [ "Pledges" ], "summary": "List pledges", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "donorId", "in": "query", "schema": { "type": "string" } }, { "name": "fundId", "in": "query", "schema": { "type": "string" } }, { "name": "campaignId", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ACTIVE", "CANCELLED" ] } }, { "name": "sortBy", "in": "query", "description": "When omitted, pledges are ordered by createdAt descending. Progress sort loads computed fulfillment for filtered pledges.", "schema": { "type": "string", "enum": [ "donor", "fund", "campaign", "pledged", "fulfilled", "progress", "pace", "status", "createdAt" ] } }, { "name": "sortDir", "in": "query", "description": "When sortBy is sent, ascending or descending order. Omit with sortBy to accept server defaults (typically desc).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated pledges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PledgeListResponse" }, "examples": { "default": { "$ref": "#/components/examples/PledgeListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Pledges" ], "summary": "Create pledge", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePledge" }, "examples": { "annual": { "value": { "donorId": "cm456def789ghi", "fundId": "cm789ghi012jkl", "totalAmount": 12000, "startDate": "2026-01-01", "endDate": "2026-12-31" } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created pledge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pledge" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/pledges/{id}": { "get": { "tags": [ "Pledges" ], "summary": "Get pledge", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Pledge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pledge" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Pledges" ], "summary": "Update pledge", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePledge" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated pledge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pledge" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Pledges" ], "summary": "Delete pledge", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/households": { "get": { "tags": [ "Households" ], "summary": "List households", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Paginated households", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HouseholdListResponse" }, "examples": { "default": { "$ref": "#/components/examples/HouseholdListExample" } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "post": { "tags": [ "Households" ], "summary": "Create household", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHousehold" }, "examples": { "family": { "value": { "name": "Johnson Family", "primaryContactId": "cm456def789ghi" } } } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Created household", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Household" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/households/{id}": { "get": { "tags": [ "Households" ], "summary": "Get household", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Household", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Household" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "patch": { "tags": [ "Households" ], "summary": "Update household", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHousehold" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated household", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Household" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Households" ], "summary": "Delete household", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/households/{id}/members": { "post": { "tags": [ "Households" ], "summary": "Add household member", "description": "Moves the donor from an existing household when necessary and atomically refreshes both households. Cross-organization references are rejected.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HouseholdMemberWrite" } } } }, "responses": { "201": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated household", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Household" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } }, "/api/v1/households/{id}/members/{donorId}": { "patch": { "tags": [ "Households" ], "summary": "Update household member", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" }, { "name": "donorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHouseholdMember" } } } }, "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Updated household", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Household" } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } }, "delete": { "tags": [ "Households" ], "summary": "Remove household member", "description": "Unlinks the donor without deleting the donor and clears primary contact when applicable.", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/PathId" }, { "name": "donorId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "examples": { "default": { "value": { "success": true } } } } } }, "400": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Bad request (missing header or invalid input)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Unauthorized (missing or invalid Bearer token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Forbidden (no access to organization or action)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "409": { "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } }, "description": "Conflict (duplicate, cross-resource ownership conflict, concurrent change, or accounting-frozen resource)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Request-Id": { "description": "Server-generated ID linking this request to API activity and audit records.", "schema": { "type": "string", "format": "uuid" } } } } } } } } }