Chariot Grant Requests API
The Grant Requests API from Chariot — 4 operation(s) for grant requests.
OpenAPI Specification
openapi: 3.0.0
info:
title: Chariot FDX Accounts Grant Requests API
version: '6.0'
description: Financial Data Exchange (FDX) v6 compatible API for read-only access to Chariot bank account data. Implements the FDX v6 standard for account information, transactions, and statements.
contact:
name: Chariot Development Team
url: https://givechariot.com/contact
email: developers@givechariot.com
servers:
- url: https://api.givechariot.com/fdx/v6
description: Production
- url: https://devapi.givechariot.com/fdx/v6
description: Staging
security:
- oauth2: []
tags:
- name: Grant Requests
paths:
/v1/grant_requests:
get:
summary: List Grant Requests
description: 'Returns a list of Grant Requests accessible to the authenticated DAF account.
Use `donor_account_id` to retrieve all Grant Requests associated with a specific donor.'
operationId: list-grant-requests
tags:
- Grant Requests
security:
- bearerAuth: []
parameters:
- name: donor_account_id
in: query
description: Filter Grant Requests by the ID of the associated [Donor Account](/api/donor-accounts).
required: false
schema:
type: string
example: donor_account_01jpjenf5q6cawy43yxfcrxhct
- name: page_limit
in: query
description: The number of results to return. Defaults to 10, max is 100.
required: false
schema:
type: integer
default: 10
- name: page_token
in: query
description: A token to retrieve the next page of results.
required: false
schema:
type: string
responses:
'200':
description: OK
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/GrantRequest'
next_page_token:
type: string
description: A token to retrieve the next page of results. Absent when there are no more results.
examples:
MixedStatuses:
summary: A page of Grant Requests across statuses
value:
results:
- id: grant_req_01jpjenf5q6cawy43yxfcrxhct
donor_account_id: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id: 0bf40881-8ee2-47fb-98ca-f58c7999aa34
status: pending
ein: 53-0196605
nonprofit_name: American Red Cross
amount_cents: 10000
frequency: one_time
form_url: https://example.org/donate
purpose: Disaster relief
note: Thank you for your service.
donor_contact:
name: Warren Buffet
email: warrenBuffet@example.com
phone: '+12125550100'
address:
line1: 3555 Farnam Street
line2: null
city: Omaha
state: NE
zip: '68131'
rejection_reason: null
created_at: '2026-04-03T14:22:00Z'
updated_at: '2026-04-03T14:22:00Z'
- id: grant_req_01jpjenf5q6cawy43yxfcrxhcu
donor_account_id: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id: 0bf40881-8ee2-47fb-98ca-f58c7999aa34
status: submitted
ein: 13-1635294
nonprofit_name: World Wildlife Fund
amount_cents: 25000
frequency: one_time
form_url: https://example.org/donate
purpose: null
note: null
donor_contact:
name: Warren Buffet
email: warrenBuffet@example.com
phone: '+12125550100'
address:
line1: 3555 Farnam Street
line2: null
city: Omaha
state: NE
zip: '68131'
rejection_reason: null
created_at: '2026-03-28T10:05:00Z'
updated_at: '2026-03-29T08:00:00Z'
- id: grant_req_01jpjenf5q6cawy43yxfcrxhcv
donor_account_id: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id: 0bf40881-8ee2-47fb-98ca-f58c7999aa34
status: rejected
ein: 13-1788491
nonprofit_name: Doctors Without Borders
amount_cents: 500000
frequency: one_time
form_url: https://example.org/donate
purpose: null
note: null
donor_contact:
name: Warren Buffet
email: warrenBuffet@example.com
phone: '+12125550100'
address:
line1: 3555 Farnam Street
line2: null
city: Omaha
state: NE
zip: '68131'
rejection_reason: Grant amount exceeds donor's available balance.
created_at: '2026-03-20T16:11:00Z'
updated_at: '2026-03-21T09:30:00Z'
next_page_token: c3f685f2-2dda-4956-815b-39867a5e5638
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/grant_requests/{id}:
get:
summary: Get Grant Request
description: Retrieve a Grant Request with the given ID.
operationId: get-grant-request
tags:
- Grant Requests
security:
- bearerAuth: []
parameters:
- name: id
in: path
description: The unique ID of the Grant Request.
required: true
schema:
type: string
responses:
'200':
description: OK
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/GrantRequest'
examples:
Pending:
$ref: '#/components/examples/GrantRequestPendingOutput'
AwaitingAccountDecision:
$ref: '#/components/examples/GrantRequestAwaitingAccountDecisionOutput'
Submitted:
$ref: '#/components/examples/GrantRequestSubmittedOutput'
Rejected:
$ref: '#/components/examples/GrantRequestRejectedOutput'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/grant_requests/{id}/submit:
post:
summary: Submit Grant Request
description: 'Confirm that you have submitted the grant in your system.
Calling this endpoint moves the Grant Request''s status to `submitted` and emits a `grant_request.updated` webhook event.
<Warning>
- The Grant Request must be in `pending` status. If the linked [Donor Account](/api/donor-accounts) is not yet `approved`, the Grant Request will be in `awaiting_account_decision` and this request returns status `412 Precondition Failed`.
- A Grant Request that is already `submitted` or `rejected` cannot be updated. Subsequent calls return status `409 Conflict`.
</Warning>'
operationId: submit-grant-request
tags:
- Grant Requests
security:
- bearerAuth: []
parameters:
- name: id
in: path
description: The unique ID of the Grant Request.
required: true
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/SubmitGrantRequest'
responses:
'200':
description: The Grant Request was submitted.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/GrantRequest'
examples:
Submitted:
$ref: '#/components/examples/GrantRequestSubmittedOutput'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'412':
$ref: '#/components/responses/PreconditionFailedError'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/grant_requests/{id}/reject:
post:
summary: Reject Grant Request
description: 'Indicate that you will not process this grant.
Calling this endpoint moves the Grant Request''s status to `rejected` and emits a `grant_request.updated` webhook event.
The Donor Account itself is unaffected; future Grant Requests from the same donor can still be processed.
<Warning>
A Grant Request that is already `submitted` or `rejected` cannot be updated. Subsequent calls return status `409 Conflict`.
</Warning>'
operationId: reject-grant-request
tags:
- Grant Requests
security:
- bearerAuth: []
parameters:
- name: id
in: path
description: The unique ID of the Grant Request.
required: true
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/RejectGrantRequest'
responses:
'200':
description: The Grant Request was rejected.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/GrantRequest'
examples:
Rejected:
$ref: '#/components/examples/GrantRequestRejectedOutput'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
BadRequestError:
description: The request is invalid or contains invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
BadRequest:
value:
type: about:blank
title: API Error
status: 400
detail: The request is invalid or contains invalid parameters.
ForbiddenError:
description: Access denied
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
Forbidden:
value:
type: about:blank
title: API Error
status: 403
detail: You do not have permission to access this resource.
NotFoundError:
description: Resource Not Found
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
NotFound:
value:
type: about:blank
title: API Error
status: 404
detail: The requested resource was not found.
ConflictError:
description: Resource Conflicts
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
Conflict:
value:
type: about:blank
title: API Error
status: 409
detail: The request conflicts with the current state of the resource.
PreconditionFailedError:
description: Precondition Failed
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
PreconditionFailed:
value:
type: about:blank
title: API Error
status: 412
detail: A precondition for the request was not met.
InternalServerError:
description: Internal Server Error
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
InternalServerError:
value:
type: about:blank
title: API Error
status: 500
detail: The server encountered an error processing your request.
AuthenticationError:
description: Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
Unauthorized:
value:
type: about:blank
title: API Error
status: 401
detail: Authentication credentials were missing or invalid.
schemas:
GrantRequestFrequency:
type: string
enum:
- one_time
- monthly
- quarterly
- annual
description: How often the donor intends this grant to recur. Only frequencies enabled in your DAF Provider settings will appear on Grant Requests.
GrantRequestDonorContact:
type: object
description: A snapshot of the donor's contact information captured for this Grant Request.
properties:
name:
type: string
email:
type: string
format: email
phone:
type: string
address:
$ref: '#/components/schemas/GrantRequestDonorContactAddress'
GrantRequestDonorContactAddress:
type: object
description: The donor's mailing address at the time of the Grant Request.
properties:
line1:
type: string
line2:
type: string
nullable: true
city:
type: string
state:
type: string
zip:
type: string
GrantRequest:
type: object
description: 'A Grant Request is a donation intent submitted by a donor through the DAFpay payment option, addressed to a specific nonprofit.
The DAF Provider is responsible for processing it in their own system and reporting the outcome back to DAFpay via the [Submit](/api/grant-requests/submit) or [Reject](/api/grant-requests/reject) endpoints.
All amounts are in US dollars.'
required:
- id
- donor_account_id
- status
- ein
- amount_cents
- frequency
- form_url
- created_at
- updated_at
properties:
id:
type: string
readOnly: true
description: The unique identifier for this Grant Request.
example: grant_req_01jpjenf5q6cawy43yxfcrxhct
donor_account_id:
type: string
description: The ID of the [Donor Account](/api/donor-accounts) this Grant Request belongs to.
example: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id:
type: string
nullable: true
description: The ID of the [Giving Pool](/api/giving_pools) the grant is being made from. Present when the donor selected a specific giving pool.
example: 0bf40881-8ee2-47fb-98ca-f58c7999aa34
status:
$ref: '#/components/schemas/GrantRequestStatus'
ein:
type: string
description: The EIN of the recipient nonprofit.
example: 12-3456789
nonprofit_name:
type: string
description: The name of the recipient nonprofit at the time of the Grant Request.
example: American Red Cross
amount_cents:
type: integer
format: int64
description: The grant amount in cents (USD).
example: 10000
frequency:
$ref: '#/components/schemas/GrantRequestFrequency'
form_url:
type: string
format: uri
description: The URL of the page where the donor submitted the DAFpay gift.
example: https://example.org/donate
purpose:
type: string
nullable: true
description: The donor's stated purpose for the grant.
note:
type: string
nullable: true
description: An optional note from the donor to the nonprofit.
donor_contact:
$ref: '#/components/schemas/GrantRequestDonorContact'
rejection_reason:
type: string
nullable: true
description: The reason provided when the Grant Request was rejected. Set when status transitions to `rejected`.
created_at:
type: string
readOnly: true
format: date-time
description: Time when this object was created, expressed in RFC 3339 format.
example: '2026-04-01T09:00:00Z'
updated_at:
type: string
readOnly: true
format: date-time
description: Time when this object was last updated, expressed in RFC 3339 format.
example: '2026-04-01T12:00:00Z'
GrantRequestStatus:
type: string
enum:
- awaiting_account_decision
- pending
- submitted
- rejected
description: 'The lifecycle status of a Grant Request.
- `awaiting_account_decision`: The linked Donor Account is not yet `approved`. Advances automatically when the account is approved.
- `pending`: The Donor Account is approved and the Grant Request is awaiting your decision.
- `submitted`: You have submitted the grant in your system. Terminal.
- `rejected`: You have rejected the grant and it will not be processed. Terminal.'
ProblemDetails:
type: object
description: RFC 7807 problem-details error (media type application/problem+json). The `status` field is an integer HTTP status code.
required:
- type
- title
- status
- detail
properties:
type:
type: string
description: A URI reference identifying the problem type.
example: about:blank
title:
type: string
description: A short, human-readable summary of the problem type.
example: API Error
status:
type: integer
description: The HTTP status code for this error.
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence.
example: The request is invalid or contains invalid parameters.
example:
type: about:blank
title: API Error
status: 400
detail: The request is invalid or contains invalid parameters.
examples:
GrantRequestPendingOutput:
summary: Grant Request awaiting your decision
value:
id: grant_req_01jpjenf5q6cawy43yxfcrxhct
donor_account_id: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id: 0bf40881-8ee2-47fb-98ca-f58c7999aa34
status: pending
ein: 53-0196605
nonprofit_name: American Red Cross
amount_cents: 10000
frequency: one_time
form_url: https://example.org/donate
purpose: Disaster relief
note: Thank you for your service.
donor_contact:
name: Warren Buffet
email: warrenBuffet@example.com
phone: '+12125550100'
address:
line1: 3555 Farnam Street
line2: null
city: Omaha
state: NE
zip: '68131'
rejection_reason: null
created_at: '2026-04-03T14:22:00Z'
updated_at: '2026-04-03T14:22:00Z'
GrantRequestAwaitingAccountDecisionOutput:
summary: Grant Request waiting on Donor Account approval
value:
id: grant_req_01jpjenf5q6cawy43yxfcrxhct
donor_account_id: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id: null
status: awaiting_account_decision
ein: 53-0196605
nonprofit_name: American Red Cross
amount_cents: 10000
frequency: one_time
form_url: https://example.org/donate
purpose: null
note: null
donor_contact:
name: Warren Buffet
email: warrenBuffet@example.com
phone: '+12125550100'
address:
line1: 3555 Farnam Street
line2: null
city: Omaha
state: NE
zip: '68131'
rejection_reason: null
created_at: '2026-04-01T11:55:00Z'
updated_at: '2026-04-01T11:55:00Z'
GrantRequestRejectedOutput:
summary: Grant Request you have rejected
value:
id: grant_req_01jpjenf5q6cawy43yxfcrxhct
donor_account_id: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id: 0bf40881-8ee2-47fb-98ca-f58c7999aa34
status: rejected
ein: 53-0196605
nonprofit_name: American Red Cross
amount_cents: 10000
frequency: one_time
form_url: https://example.org/donate
purpose: Disaster relief
note: Thank you for your service.
donor_contact:
name: Warren Buffet
email: warrenBuffet@example.com
phone: '+12125550100'
address:
line1: 3555 Farnam Street
line2: null
city: Omaha
state: NE
zip: '68131'
rejection_reason: Grant amount exceeds donor's available balance.
created_at: '2026-04-03T14:22:00Z'
updated_at: '2026-04-04T09:15:00Z'
GrantRequestSubmittedOutput:
summary: Grant Request you have submitted in your system
value:
id: grant_req_01jpjenf5q6cawy43yxfcrxhct
donor_account_id: donor_account_01jpjenf5q6cawy43yxfcrxhct
giving_pool_id: 0bf40881-8ee2-47fb-98ca-f58c7999aa34
status: submitted
ein: 53-0196605
nonprofit_name: American Red Cross
amount_cents: 10000
frequency: one_time
form_url: https://example.org/donate
purpose: Disaster relief
note: Thank you for your service.
donor_contact:
name: Warren Buffet
email: warrenBuffet@example.com
phone: '+12125550100'
address:
line1: 3555 Farnam Street
line2: null
city: Omaha
state: NE
zip: '68131'
rejection_reason: null
created_at: '2026-04-03T14:22:00Z'
updated_at: '2026-04-04T09:15:00Z'
requestBodies:
RejectGrantRequest:
description: The request to reject a Grant Request.
required: false
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: 'A human-readable reason for the rejection. Maximum length: 400 characters.'
example: Grant amount exceeds donor's available balance.
SubmitGrantRequest:
description: 'The request to submit a Grant Request.
All fields are optional — an empty body is valid.'
required: false
content:
application/json:
schema:
type: object
properties:
external_grant_id:
type: string
description: 'The DAF''s internal identifier for this grant. Setting this at submission time provides a useful audit trail and reconciliation key. Maximum length: 255 characters.'
example: ACME-GRANT-2026-00481
comment:
type: string
description: 'An optional comment recorded with the submission. Maximum length: 400 characters.'
headers:
X-Request-Id:
description: The unique identifier for the request
schema:
type: string
securitySchemes:
oauth2:
type: oauth2
description: OAuth 2.0 Bearer token. A client may hold both scopes, but each FDX authorization must contain exactly one — they are mutually exclusive per authorization. An authorization containing both will be rejected. See the Authentication page for token exchange details.
flows:
authorizationCode:
authorizationUrl: https://dashboard.givechariot.com/oauth/authorize
tokenUrl: https://api.givechariot.com/auth/oauth/token
scopes:
read:bank_accounts: Read access to bank account data
sync:connected_accounts: Sync access to connected account data