openapi: 3.0.3 info: title: Benevity API description: >- Modeled from the public Benevity API documentation at developer.benevity.org. Covers the confirmed Causes, Giving (donations), Receipts, and Spark (giving/volunteer opportunities) endpoints. Credentials are partner-gated (request-a-demo); this document reflects publicly documented paths and fields only - it does not fabricate an unverified full surface. The Location Services API is intentionally omitted here (see review.yml) because its exact request/response schema beyond the overview guide was not independently confirmed. version: '2024.8' contact: name: Benevity url: https://developer.benevity.org/ externalDocs: description: Benevity API Documentation url: https://developer.benevity.org/ servers: - url: https://skyline.benevity.org description: Giving, Causes, and Receipts API host - url: https://api.benevity.org description: Spark API host (production) - url: https://api.benevity-staging.org description: Spark API host (sandbox) tags: - name: Authorization - name: Causes - name: Giving - name: Receipts - name: Spark security: - bearerAuth: [] paths: /oauth2/token: post: operationId: getAccessToken tags: - Authorization summary: Obtain an OAuth 2.0 client-credentials access token description: >- Server-to-server OAuth 2.0 client credentials grant. Send Basic Authentication with base64-encoded `client_id:client_secret`. Tokens are valid for `expires_in` seconds (typically 3600) and should be reused until expiry rather than fetched per request. security: - basicAuth: [] responses: '200': description: Access token issued content: application/json: schema: type: object properties: access_token: type: string description: JWT bearer token token_type: type: string example: Bearer expires_in: type: integer example: 3600 /search/causes: get: operationId: searchCauses tags: - Causes summary: Search the Benevity Cause Database parameters: - name: q in: query required: true schema: type: string description: Search term matched against cause name, description, and tags. - name: visibility in: query schema: type: string enum: [match, donate, program, nominate, ineligible, inactive] - name: category in: query schema: type: string description: NTEE category/subcategory filter. - name: country in: query schema: type: string description: ISO 3166 country code. - name: state in: query schema: type: string description: ISO 3166-2 state/province code. - name: search_location in: query schema: type: string description: '"latitude,longitude" for proximity search.' - name: autocorrect in: query schema: type: boolean - name: page in: query schema: type: integer - name: page_size in: query schema: type: integer default: 25 - name: sort in: query schema: type: string responses: '200': description: Matching causes content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string attributes: type: object properties: name: type: string city: type: string state: type: string country: type: string categories: type: array items: type: string visibility: type: string status: type: object snippets: type: array items: type: string meta: type: object links: type: object /donations: post: operationId: createPostpaidDonation tags: - Giving summary: Create a postpaid company donation description: >- Submits a donation settled monthly against a donation report invoiced to the client company, rather than captured immediately by card. requestBody: required: true content: application/json: schema: type: object properties: destination: type: object properties: recipientId: type: string foundationId: type: string funds: type: object properties: paymentType: type: string currencyCode: type: string amount: type: integer description: Amount in lowest currency denomination (e.g. cents). donor: type: object properties: fullName: type: string email: type: string receipted: type: boolean address: type: object metadata: type: object additionalProperties: type: string description: Up to 100 custom key/value pairs. required: - destination - funds responses: '201': description: Donation accepted content: application/json: schema: type: object properties: id: type: string description: UUID type: type: string example: donations destination: type: object funds: type: object donor: type: object metadata: type: object state: type: object properties: processingStatus: type: string example: ACCEPTED statusLastUpdated: type: string format: date-time /payments/card/transactions: post: operationId: createCreditCardDonation tags: - Giving summary: Create a prepaid credit card donation description: >- Captures a donation immediately via a tokenized card payment (BlueSnap-backed processor), optionally split across multiple cause allocations, with optional Gift Aid (UK) handling. requestBody: required: true content: application/json: schema: type: object properties: companyCode: type: string total: type: integer currencyCode: type: string paymentConfig: type: object properties: token: type: string merchantAccountId: type: string processor: type: string example: BLUESNAP cardHolder: type: object referenceNumber: type: string adapter: type: string example: Adapter.General purchaseItems: type: array items: type: object properties: itemTotalAmountCents: type: integer allocations: type: array items: type: object properties: causeCode: type: string amountCents: type: integer giftAid: type: boolean description: type: string softDescriptor: type: string payerBusinessName: type: string required: - companyCode - total - currencyCode - paymentConfig - referenceNumber - purchaseItems responses: '201': description: Transaction created content: application/json: schema: type: object properties: transactionId: type: string creditCardId: type: string processorTransactionId: type: string referenceNumber: type: string backendReceiptId: type: string amount: type: object properties: totalAmountCents: type: integer currencyCode: type: string transactionFee: type: number /receipts/{backendReceiptId}: get: operationId: getReceiptPdf tags: - Receipts summary: Download a donation receipt as PDF parameters: - name: backendReceiptId in: path required: true schema: type: string example: test_receipt_id_4G801PXR6W responses: '200': description: Receipt PDF content: application/pdf: schema: type: string format: binary /receipts/{backendReceiptId}/email: post: operationId: emailReceipt tags: - Receipts summary: Email a donation receipt to the donor parameters: - name: backendReceiptId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: email: type: string required: - email responses: '202': description: Receipt email queued for delivery /search/givingopportunities: get: operationId: searchGivingOpportunities tags: - Spark summary: Search a company's giving opportunities (Spark API) parameters: - name: q in: query required: true schema: type: string - name: search_location in: query schema: type: string - name: autocorrect in: query schema: type: boolean responses: '200': description: Matching giving opportunities content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer title: type: string description: type: string image_url: type: string creator_id: type: string creator_name: type: string creator_type: type: string peer_match: type: boolean company_match: type: boolean portfolio_code: type: string projects: type: array items: type: object causes: type: array items: type: object snippets: type: array items: type: string /search/volunteeropportunities: get: operationId: searchVolunteerOpportunities tags: - Spark summary: Search a company's volunteer opportunities (Spark API) parameters: - name: q in: query required: true schema: type: string - name: search_location in: query schema: type: string - name: autocorrect in: query schema: type: boolean - name: filter[ends_after] in: query schema: type: string format: date-time - name: filter[starts_before] in: query schema: type: string format: date-time - name: filter[minimum_open_spots] in: query schema: type: integer - name: filter[has_location] in: query schema: type: boolean - name: filter[interests] in: query schema: type: string - name: filter[skills] in: query schema: type: string - name: filter[temporal_type] in: query schema: type: string enum: [ongoing, time_bounded] responses: '200': description: Matching volunteer opportunities content: application/json: schema: type: object properties: volunteer_opportunities: type: array items: type: object properties: id: type: integer title: type: string description: type: string location_notes: type: string start_timestamp: type: string format: date-time end_timestamp: type: string format: date-time time_zone: type: string cause_id: type: string cause_name: type: string image_url: type: string hero_image_url: type: string cause_logo_url: type: string address: type: object characteristics: type: array items: type: string interests: type: array items: type: string skills: type: array items: type: string shifts: type: array items: type: object geo_coordinates: type: object components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT basicAuth: type: http scheme: basic