Chariot Grants API
The Grants API from Chariot — 4 operation(s) for grants.
OpenAPI Specification
openapi: 3.0.0
info:
title: Chariot FDX Accounts Grants 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: Grants
paths:
/v1/grants:
get:
summary: List Grants
description: 'Returns a list of all grants for a given Connect. This API allows for paginating over many results.
DAF providers can use `donor_account_id` to filter Grant Requests associated with a specific [Donor Account](/api/donor-accounts).'
operationId: list-grants
tags:
- Grants
security:
- bearerAuth: []
parameters:
- name: connect_id
in: query
description: the `id` of the Connect object. This can be used to filter the grants by a specific Connect if you have more than one.
schema:
type: string
required: false
example: live_2d821da0ed8bc7256e260f4eb5244f2d8f06c576342f922ba2f0a416d8c98002
- name: donor_account_id
in: query
description: Filter grants by a specific [Donor Account](/api/donor-accounts). Use this to retrieve all Grant Requests associated with a given donor.
schema:
type: string
required: false
example: donor_account_01jpjenf5q6cawy43yxfcrxhct
- name: pageLimit
in: query
description: the number of results to return; defaults to 10, max is 100
schema:
type: integer
default: 10
- name: pageToken
in: query
description: A token to use to retrieve the next page of results. This is useful for paginating over many pages of results. If set, all other arguments are expected to be kept the same as previous calls and the value of this field should be from the nextPageToken in the previous response.
schema:
type: string
responses:
'200':
$ref: '#/components/responses/ListGrantsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
post:
summary: Create Grant
description: 'Create and submit a new grant. This should be used to capture a grant intent from an authorized DAFpay workflow session and submit the grant request to the DAF sponsor.
On initial creation of the grant, this request will return a 201 Created status. On subsequent requests, the request will return status 200 OK.
<Warning>
Error handling:
- The grant must be captured within 15 minutes of authorization otherwise the request will return status `410 Gone`.
- If this request is submitted while this grant is already being processed, the request will return status `409 Conflict`.
- The amount must be in whole dollar increments (rounded to the nearest hundred) as currently DAFs only accept whole dollar grants otherwise the request will return status `400 Bad Request`.
- The amount must be greater than or equal to the minimum grant amount for the DAF otherwise the request will return status `400 Bad Request`.
- The amount must be less than or equal to the user''s DAF account balance otherwise the request will return status `400 Bad Request`.
- Any inputs exceeding the maximum allowed length will be automatically truncated.
</Warning>'
operationId: create-grant
tags:
- Grants
security:
- bearerAuth: []
requestBody:
$ref: '#/components/requestBodies/GrantCaptureRequest'
responses:
'201':
description: Created
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
Location:
description: The URI reference of the created grant object.
schema:
type: string
format: uri
content:
application/json:
schema:
$ref: '#/components/schemas/Grant'
examples:
Simple:
$ref: '#/components/examples/GrantOutput'
'200':
description: The grant
content:
application/json:
schema:
$ref: '#/components/schemas/Grant'
examples:
Simple:
$ref: '#/components/examples/GrantOutput'
'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'
'410':
$ref: '#/components/responses/GoneError'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/grants/{id}:
get:
summary: Get Grant
description: Retrieve a grant with the given ID.
operationId: get-grant
tags:
- Grants
security:
- bearerAuth: []
parameters:
- name: id
in: path
description: 'The unique id of the grant.
The format should be a v4 UUID according to RFC 4122.'
schema:
type: string
format: uuid
required: true
example: 10229488-08d2-4629-b70c-a2f4f4d25344
responses:
'200':
description: OK
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/Grant'
examples:
Simple:
$ref: '#/components/examples/GrantOutput'
'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/simulations/grants/{id}/complete:
post:
summary: 'Sandbox: Complete a grant'
description: 'Simulates the DAF sponsor completing a grant. Transitions the grant status to `completed`.
<Note title="Sandbox Only" icon="fa-light fa-atom-simple">
This API is only available in the sandbox environment.
</Note>
'
operationId: simulateGrantCompletion
tags:
- Grants
security:
- bearerAuth: []
parameters:
- name: id
in: path
description: The unique identifier for the grant.
required: true
schema:
type: string
format: uuid
example: 10229488-08d2-4629-b70c-a2f4f4d25344
responses:
'200':
description: The updated grant
content:
application/json:
schema:
$ref: '#/components/schemas/Grant'
'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/simulations/grants/{id}/cancel:
post:
summary: 'Sandbox: Cancel a grant'
description: 'Simulates the DAF sponsor canceling the grant. Transitions the grant status to `canceled`.
<Note title="Sandbox Only" icon="fa-light fa-atom-simple">
This API is only available in the sandbox environment.
</Note>
'
operationId: simulateGrantCancellation
tags:
- Grants
security:
- bearerAuth: []
parameters:
- name: id
in: path
description: The unique identifier for the grant.
required: true
schema:
type: string
format: uuid
example: 10229488-08d2-4629-b70c-a2f4f4d25344
responses:
'200':
description: The updated grant
content:
application/json:
schema:
$ref: '#/components/schemas/Grant'
'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'
components:
schemas:
Grant:
type: object
description: A Grant represents a successfully initiated grant request with a Donor Advised Fund. Grants are created when a person interacts with an instance of Chariot Connect and successfully submits a grant and completes the workflow. There can be many grants associated with a Connect object and therefore a nonprofit.
required:
- id
- workflowSessionId
- fundId
- amount
properties:
id:
type: string
readOnly: true
description: The unique identifier for the object
format: uuid
example: cfe09e64-6a74-4dab-a565-361185a6f248
userFriendlyId:
type: string
readOnly: true
description: Often referred to as the "Chariot ID", this is the ID that will be included in the payment from the DAF provider.
example: chariot-1234455
deprecated: true
trackingId:
type: string
readOnly: true
description: The tracking ID for the grant
example: L9E182VBGP
workflowSessionId:
type: string
readOnly: true
description: ID of the Connect Workflow Session associated with this grant
format: uuid
example: 2d4b2a43-a5b4-4be1-ad1f-f932016ca4a6
fundId:
type: string
readOnly: true
description: ID of the donor advised fund
example: daf-id
donor_account_id:
type: string
readOnly: true
description: 'ID of the [Donor Account](/api/donor-accounts) that this grant was submitted from.
Present on grants submitted by donors who authenticated through the DAFpay Donor Account flow.
Grants submitted without a linked Donor Account will not have this field set.'
example: donor_account_01jpjenf5q6cawy43yxfcrxhct
externalGrantId:
type: string
description: ID of the grant associated with the donor advised fund
example: 897823sdjf8sfjs
createdAt:
type: string
readOnly: true
format: date-time
description: Time when this object was created; expressed in RFC 3339 format
example: '2020-01-31T23:00:00Z'
updatedAt:
type: string
readOnly: true
format: date-time
description: Time when this object was last updated; expressed in RFC 3339 format
example: '2020-01-31T23:59:59Z'
amount:
type: number
format: integer
description: The grant amount expressed in units of whole cents
example: 15000
status:
type: string
description: The status of the grant
example: Initiated
feeDetail:
type: object
readOnly: true
description: The fee detail of the grant
properties:
total:
type: number
format: integer
description: The total fee amount expressed in units of cents
example: 1500
contributions:
type: array
items:
$ref: '#/components/schemas/ContributionFeeDetail'
description: The list of fee contributions for this grant
metadata:
type: object
description: A map of arbitrary string keys and values to store information about the object
additionalProperties:
type: string
firstName:
type: string
description: The donor's first name
example: Warren
lastName:
type: string
description: The donor's last name
example: Buffet
phone:
type: string
description: The donor's phone number
example: '1237861020'
email:
type: string
description: The donor's email
example: warrenBuffet@example.com
note:
type: string
description: An note inputted by the user at submisson
example: Please dedicate in memory of grandma
statuses:
type: array
items:
$ref: '#/components/schemas/GrantStatus'
description: The list of grant statuses for this grant
paymentChannel:
type: string
readOnly: true
description: 'The payment channel for the grant. This is useful to know how the grant will be sent.
The payment channel will be one of the following:
- dafpay_network: Grant will be sent to the DAFPay Network 501(c)(3) nonprofit organization (EIN: 93-1372175). The DAFPay Network will then review and process the grant and send the funds to the intended recipient.
- direct: Grant will be sent directly to the intended recipient.'
enum:
- dafpay_network
- direct
example: direct
address:
$ref: '#/components/schemas/GrantAddress'
GrantStatus:
type: object
required:
- id
- createdAt
- status
properties:
id:
type: string
readOnly: true
description: The unique identifier for the object
format: uuid
example: cfe09e64-6a74-4dab-a565-361185a6f248
createdAt:
type: string
readOnly: true
format: date-time
description: Time when this object was created; expressed in RFC 3339 format
example: '2020-01-31T23:00:00Z'
status:
type: string
enum:
- awaiting_account_approval
- awaiting_daf_submission
- initiated
- canceled
description: "The status of the grant.\n * awaiting_account_approval: The linked Donor Account is not yet `approved`. The grant advances automatically when the Account is approved.\n * awaiting_daf_submission: The Account is approved and the grant is ready for the DAF to submit in their system.\n * initiated: The DAF has submitted the grant. Terminal.\n * canceled: The DAF has canceled the grant. Terminal.\n"
example: awaiting_daf_submission
comment:
type: string
description: The user comment for the update
example: The grant has been received by the nonprofit
GrantAddress:
type: object
properties:
line1:
type: string
description: 'Address line 1 (e.g. street, PO Box, or company name). Maximum length: 255 characters.'
line2:
type: string
description: 'Address line 2 (e.g. apartment, suite, unit, or building). Maximum length: 255 characters.'
city:
type: string
description: 'City, district, suburb, town, or village.. Maximum length: 255 characters.'
state:
type: string
description: 'State, county, province, or region. Maximum length: 255 characters.'
postalCode:
type: string
description: 'ZIP or postal code. Maximum length: 255 characters.'
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.
ContributionFeeDetail:
type: object
required:
- name
- amount
properties:
name:
type: string
description: 'The name of the party charging the fee. This is an informational field.
If you need to differentiate between fees charged by different parties, you should use the `feeType` field.
'
example: Chariot
amount:
type: number
format: integer
description: The fee contribution amount expressed in units of cents
example: 1500
feeType:
type: string
description: "This indicates the source of a fee contribution.\n * chariot: Chariot's processing fee\n * daf: The DAF's processing fee\n * fundraising_application: The fundraising application's processing fee\n"
example: chariot
enum:
- chariot
- daf
- fundraising_application
examples:
GrantOutput:
summary: Simple grant output
value:
id: 1e60800e-849b-43d1-870e-57afc8d75473
workflowSessionId: cfe09e64-6a74-4dab-a565-361185a6f248
fundId: daf-id
createdAt: '2021-08-10 15:00:00.000'
updatedAt: '2021-08-11 15:34:00.000'
amount: 15000
status: Initiated
responses:
ListGrantsResponse:
description: The response for Grants.list
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Grant'
nextPageToken:
type: string
nullable: true
description: A cursor token to use to retrieve the next page of results by making another API call to the same endpoint with the same parameters (only changing the pageToken). If specified, then more results exist on the server that were not returned, otherwise no more results exist on the server.
example:
results:
- id: 1e60800e-849b-43d1-870e-57afc8d75473
workflowSessionId: cfe09e64-6a74-4dab-a565-361185a6f248
fundId: daf-id
createdAt: '2021-08-10 15:00:00.000'
updatedAt: '2021-08-11 15:34:00.000'
amount: 15000
status: Initiated
nextPageToken: c3f685f2-2dda-4956-815b-39867a5e5638
GoneError:
description: Resource Gone or Expired
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
Gone:
value:
type: about:blank
title: API Error
status: 410
detail: The resource is no longer available.
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.
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.
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.
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.
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.
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.
headers:
X-Request-Id:
description: The unique identifier for the request
schema:
type: string
requestBodies:
GrantCaptureRequest:
description: 'The request to create and submit a grant. This is useful to capture a grant intent associated with DAFpay workflow session.
The request should specify the grant amount. This is the amount submitted for processing by the DAF.'
required: true
content:
application/json:
schema:
type: object
required:
- workflowSessionId
- amount
properties:
workflowSessionId:
type: string
description: 'The identifier of the donor''s DAFpay Workflow Session.
See [Capturing Grant Intents](/guides/dafpay/integrating-dafpay/integration#capturing-grant-intents) for how to get this value from the DAFpay `CHARIOT_SUCCESS` event.'
amount:
type: number
example: 15000
description: 'The grant amount in cents that will be processed by Chariot and submitted to the DAF.
This amount must be in whole dollar increments (rounded to the nearest hundred) as currently
all DAFs only accept whole dollar grant amounts.'
applicationFeeAmount:
type: number
example: 3000
description: 'This parameter specifies the fee your platform plans to take from the grant in cents.
This is a fee in addition to Chariot''s processing fee. With application fees,
Chariot collects the fee you determine from the nonprofit and passes it to your platform.
Please note that platform fees are only taken when the grant is successfully received by the nonprofit.
The sum of Chariot''s fee and the applicationFeeAmount cannot exceed 5% of the grant''s amount.
If the fee limit is exceeded, a `400 Bad Request` error will be returned.'
donor:
type: object
properties:
firstName:
type: string
description: 'The first name of the donor. Maximum length: 255 characters.'
lastName:
type: string
description: 'The last name of the donor. Maximum length: 255 characters.'
email:
type: string
description: 'The email address of the donor. Maximum length: 255 characters.'
phone:
type: string
description: 'The phone number of the donor. Maximum length: 255 characters.'
address:
$ref: '#/components/schemas/GrantAddress'
note:
type: string
description: 'A note the donor wants to send to the nonprofit. Maximum length: 400 characters.'
designation:
type: string
description: 'The designation to include on the grant. If this is left blank, "Where needed most" will be used.
Note that including a custom designation may cause the grant approval process to take longer.
Maximum length: 100 characters.'
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