openapi: 3.0.1
info:
  title: Benevity API
  description: Public API endpoints for Benevity
  version: 1.0.0
  contact:
    email: api-support@benevity.com
    url: 'https://benevity.com'
servers:
  - url: https://api.benevity.org
tags:
  - name: Giving API
    description: API endpoints related to giving.
  - name: Search
    description: API endpoints related to search.
  - name: Autocomplete
    description: API endpoints related to autocomplete.
  - name: Causes API
    description: API endpoints related to causes.
paths:
  /autocomplete/causes:
    get:
      security:
        - Oauth2:
            - benevity/api
      tags:
        - Autocomplete
      operationId: causeAutocomplete
      summary: Autocomplete suggestions for cause names.
      description: |
        Keystroke based predictions for cause names.
        (Minimum 3 keystrokes are required to get predictions).
      parameters:
        - name: q
          in: query
          required: true
          description: A string (e.g. an end user's search box input) used to get autocomplete results.
          schema:
            type: string
            example: cat shelt
        - $ref: '#/components/parameters/searchLocation'
        - $ref: '#/components/parameters/country'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/visibility'
        - $ref: '#/components/parameters/rulesetTag'
        - $ref: '#/components/parameters/foundation'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/includeChildren'
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                description: Return up to 10 autocomplete results for the original query term. Results are ranked from best to worst.
                type: object
                required:
                  - data
                properties:
                  data:
                    description: Cause autocomplete result data.
                    type: array
                    items:
                      description: Predictions returned from the autocomplete request.
                      type: object
                      required:
                        - type
                        - id
                        - attributes
                      properties:
                        type:
                          description: The type of result.
                          type: string
                          enum:
                            - predictions
                        id:
                          description: The ID for the prediction.
                          type: string
                          example: p124-100823830RR0001
                        attributes:
                          description: Details of the autocomplete result.
                          type: object
                          required:
                            - term
                            - reference
                            - content_type
                          properties:
                            term:
                              description: The predicted term.
                              type: string
                              example: Australian Wildfires
                            reference:
                              description: >-
                                Unique identifier of a project or cause that contains the predicted term. The project identifier is the
                                cause identifier appended with a forward-slash '/' separator and the project's 10-digit alphanumeric
                                identifier.
                              type: string
                              example: 124-1234567890/PR0J3KC0D3
                            content_type:
                              description: The type of the prediction.
                              type: string
                              example: causes
        '400':
          description: Bad Request
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1search~1causes/get/responses/400/content/application~1vnd.api%2Bjson/schema'
              example:
                errors:
                  - code: validation
                    title: One or more validation errors were present in the request.
                    detail: Invalid visibility parameter.
                    source:
                      parameter: visibility
        '500':
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1search~1causes/get/responses/400/content/application~1vnd.api%2Bjson/schema'
              example:
                errors:
                  - code: internal_server_error
                    title: An unknown internal error occurred.
  /payments/ping:
    get:
      summary: Ping Benevity payments back end.
      operationId: pingBenevityPayments
      description: >
        Check if the Benevity payments back end is reachable or not.
      tags:
        - Giving API
      responses:
        '200':
          description: Return the pong result to indicate success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '503':
          description: Benevity Api service not reachable or available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
      security:
        - Oauth2:
            - benevity/api
  /payments/card/payment-configuration:
    post:
      summary: Returns the necessary configuration to process a payment.
      operationId: createPaymentConfig
      description: >
        Returns the necessary configuration data to complete a Credit Card Transaction. This will create:

        A Credit Card Payment Field Token.
        A Payments User to be used for the Transaction.

        This will also define the required fields based on the country and the recipient that the funds are being routed to.
      tags:
        - Giving API
      requestBody:
        description: A Payment Fields Token request object.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentFieldsTokenRequest'
      responses:
        '201':
          description: Payment Fields Token created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentFieldsTokenResponse'
        '400':
          description: Invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '402':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        default:
          description: Unexpected Error.
      security:
        - Oauth2:
            - benevity/api
  /payments/card/transactions:
    post:
      summary: Create a Card Transaction.
      operationId: createTransaction
      description: >
        Creates a transaction on the backend to charge the credit card associated with the payment token.
      tags:
        - Giving API
      requestBody:
        description: Transaction object for the Transaction that is to be added to the system.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserTransactionRequest'
      responses:
        '201':
          description: Transaction successfuly created in the system. Transaction object is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
        '400':
          description: Invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '402':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenevityException'
        default:
          description: Unexpected Error.
      security:
        - Oauth2:
            - benevity/api
  /receipts/{receiptId}/email:
    post:
      tags:
        - Giving API
      summary: Email a receipt
      description: |
        Email a receipt by providing a receipt id.
      operationId: emailReceipt
      parameters:
        - name: receiptId
          in: path
          description: The unique receipt id of the donation for which you wish to retrieve the receipt for
          required: true
          schema:
            type: string
      requestBody:
        description: Includes the email address to which the receipt should be sent to
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/ReceiptEmailRequest'
        required: true
      responses:
        202:
          description: Receipt email request has been sent to the mail server
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected Error
          content: {}
      security:
        - Oauth2:
            - benevity/api
  /receipts/{receiptId}:
    get:
      tags:
        - Giving API
      summary: Get a receipt PDF given a receipt id
      description: Get a receipt PDF by providing a receipt id.<br>
      operationId: getReceiptPdf
      parameters:
        - name: receiptId
          in: path
          description: The unique receipt id of the donation for which you wish to retrieve the receipt for
          required: true
          schema:
            type: string
      responses:
        200:
          description: The donation receipt
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected Error
          content: {}
      security:
        - Oauth2:
            - benevity/api
  /donations/ping:
    get:
      tags:
        - Giving API
      summary: Ping the Benevity donation service.
      operationId: pingDonationService
      description: Check if the Benevity donation service is reachable or not.
      responses:
        '200':
          description: Return the pong result to indicate success.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PingResponse'
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalServerError'
        503:
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected Error.
          content: {}
      security:
            - Oauth2:
                - benevity/api
  /donations:
    post:
      tags:
        - Giving API
      summary: Create a donation.
      operationId: createDonations
      requestBody:
        description: The request to create a donation.
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/CreateDonationRequest'
        required: true
      responses:
        202:
          description: Donation accepted.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CreateDonationResponse'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected Error.
          content: {}
      security:
          - Oauth2:
              - benevity/api
    get:
      tags:
        - Giving API
      summary: >-
        Get your submitted donations with optional filters; paginated.
      description: >-
        Get donations submitted to the donation service. Supports filtering by status, bulk ID and pagination.
      operationId: getDonations
      parameters:
        - in: query
          name: filter[bulk]
          schema:
            type: string
          description: The unique identifier of the bulk intent.
          required: false
        - in: query
          name: filter[status]
          schema:
            type: string
          description: A specific donation status.
          required: false
        - in: query
          name: page[before]
          schema:
            type: string
          description: The value obtained from `links.prev` on a prior request to show the prior page of results, if any.
          required: false
        - in: query
          name: page[after]
          schema:
            type: string
          description: The value obtained from `links.next` on a prior request to show the next page of results.
          required: false
        - in: query
          name: page[size]
          schema:
            type: number
          description: Desired number of records per page, defaults to 1000. Larger values are best-effort, and may still be truncated for performance reasons. Refer to body attributes `meta.page.rangeTruncated` or the presence of `links.next`/`links.prev` to access additional records.
          required: false
      responses:
        200:
          description: Successfully retrieved donations
          content:
            application/vnd.api+json:
              schema:
                  type: array
                  items:
                    $ref: '#/components/schemas/DonationsArrayResponseObject'
                  example:
                    meta:
                      count: 2
                      page:
                        rangeTruncated: true
                    links:
                      prev: /donations?page[before]=CursorToPreviousPage
                      next: /donations?page[after]=CursorToNextPage
                    data:
                      - type: "donations"
                        id: "68cad167-99a8-4b0f-adee-32659909d8e8"
                        attributes:
                            destination:
                              foundationId: "1XABCDE4UT"
                              recipientId: "124-119219814RR0001"
                            funds:
                              amount: 111
                              currencyCode: "CAD"
                              paymentType: "DONATION_REPORT"
                              source: "COMPANY"
                            donor:
                              fullName: "Benevity User 1"
                              email: "test@benevity.com"
                              receipted: true
                              address:
                                  line1: "5555 Calgary St"
                                  line2: "Suite 101"
                                  city: "Calgary"
                                  state: "AB"
                                  zip: "T0A 1B2"
                                  country: "CA"
                            metadata:
                              vendor-id: abc-12382
                              location: NW Calgary
                              refill_date: 05/15/2023
                        state:
                            processingStatus: "ACCEPTED"
                            statusLastUpdated: "2021-07-23T17:34:01.755Z"
                        bulkId: "0cf8faf5-c6f4-4c27-8235-80ae832d1525"
                      - type: "donations"
                        id: "323bd15f-332d-43a6-82e4-83bc6f4a45b8"
                        attributes:
                            destination:
                                foundationId: "1XABCDE4UT"
                                recipientId: "124-119219814RR0001"
                            funds:
                                amount: 333
                                currencyCode: "CAD"
                                paymentType: "DONATION_REPORT"
                                source: "COMPANY"
                            state:
                                processingStatus: "ACCEPTED"
                                statusLastUpdated: "2021-07-24T18:25:03.132Z"
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected Error.
          content: {}
      security:
        - Oauth2:
            - benevity/api
  /donations/{id}:
    get:
      tags:
        - Giving API
      summary: Get the details of a donation by donation id.
      operationId: getDonationDetails
      parameters:
        - name: id
          in: path
          description: The unique identifier of the donation.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully retrieved donation details by id.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetDonationResponse'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected Error.
          content: {}
      security:
          - Oauth2:
              - benevity/api
  /donations/bulk-intents:
    post:
      tags:
        - Giving API
      summary: >-
        Create a bulk donation intent.
      description: >-
        Create a bulk donation intent. Will return an S3 Presigned POST URL that clients can use to upload donation files.
        The maximum upload size is 500MB per file. The time-to-live for the presigned URL is 10 minutes.
      operationId: createBulkIntent
      responses:
        200:
          description: Bulk donation intent created.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CreateBulkIntentResponse'
              example:
                data:
                  type: "bulkDonationIntent"
                  id: "550e8400-e29b-41d4-a716-446655440000"
                  attributes:
                    status: PENDING
                    createdAt: '2021-06-08T18:18:14.630Z'
                    expiresAt: '2021-06-08T18:28:14.630Z'
                    url: "https://s3.us-east-1.amazonaws.com/env-benevity-donation-service-private"
                    fields:
                      key: bulk/123e4567-e89b-12d3-a456-426614174000/donations.gz
                      bucket: env-benevity-donation-service-private
                      "X-Amz-Algorithm": "AWS4-HMAC-SHA256"
                      "X-Amz-Credential": "A..../us-east-1/s3/aws4_request"
                      "X-Amz-Date": "20210608T1818214Z"
                      "X-Amz-Security-Token": "FQoGZXIvYXdzEMb//////////...i9kOQF"
                      "Policy": "eyJleHBpcmF0a...UYifV19"
                      "X-Amz-Signature": "05ed426704d359c1c68b1....6caf2f3492e"
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected Error.
          content: {}
      security:
        - Oauth2:
            - benevity/api
  /donations/bulk-intents/:id:
    get:
      tags:
        - Giving API
      summary: >-
        Get the status of a bulk intent by id.
      description: >-
        Get the current status of the bulk-intent using the ID returned in the response from POST /donations/bulk-intents
      operationId: getBulkIntent
      parameters:
        - in : header
          name: id
          description: The unique identifier of the bulk intent.
          required: true
          schema:
            type: string
      responses:
            200:
              description: Successfully retrieved bulk intent status by id.
              content:
                application/vnd.api+json:
                  schema:
                    $ref: '#/components/schemas/GetBulkIntentResponse'
                  examples:
                    PENDING:
                      value:
                        data:
                          type: "bulkDonationIntent"
                          id: "550e8400-e29b-41d4-a716-446655440000"
                          attributes:
                            status: PENDING
                            createdAt: '2021-06-08T18:18:14.630Z'
                            expiresAt: '2021-06-08T18:28:14.630Z'
                    VALIDATED:
                      value:
                        data:
                          type: "bulkDonationIntent"
                          id: "550e8400-e29b-41d4-a716-446655440000"
                          attributes:
                            status: VALIDATED
                            createdAt: '2021-06-08T18:18:14.630Z'
                            updatedAt: '2021-06-08T18:28:14.630Z'
                          links:
                            related:
                              meta:
                                uploaded: 3
                    PROCESSED:
                      value:
                        data:
                          type: "bulkDonationIntent"
                          id: "26e1e6b7-4936-46d1-986d-bbfbf6ebf81e"
                          attributes:
                            status: "PROCESSED"
                            createdAt: "2021-07-22T22:28:38.599Z"
                            updatedAt: "2021-07-22T22:30:08.342Z"
                          links:
                            related:
                              href: "https://api.benevity.org/donations?filter[bulk]=26e1e6b7-4936-46d1-986d-bbfbf6ebf81e"
                              meta:
                                uploaded: 3
                                accepted: 3
                    ERROR (donations):
                      value:
                        data:
                          type: "bulkDonationIntent"
                          id: "550e8400-e29b-41d4-a716-446655440000"
                          attributes:
                            status: ERROR
                            createdAt: '2021-06-08T18:18:14.630Z'
                            errors:
                              code: "INVALID_BULK_DONATIONS"
                              title: "Error validating bulk intent."
                              detail: "File contains invalid donations for bulk intent ID: 550e8400-e29b-41d4-a716-446655440000"
                              links:
                                href: "https://s3.us-east-1.amazonaws.com/env-benevity-donation-service-private/bulk/550e8400-e29b-41d4-a716-446655440000/donation-errors.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=...&X-Amz-SignedHeaders=host&x-id=GetObject"
                            updatedAt: '2021-06-08T18:28:14.630Z'
                          links:
                            related:
                              meta:
                                uploaded: 3
                                invalid: 1
                    ERROR (file):
                      value:
                        data:
                          type: "bulkDonationIntent"
                          id: "550e8400-e29b-41d4-a716-446655440000"
                          attributes:
                            status: ERROR
                            createdAt: '2021-06-08T18:18:14.630Z'
                            errors:
                              code: "INVALID_BULK_DONATIONS"
                              title: "Error validating bulk intent."
                              detail: "Could not parse document string to JSON"
                              links:
                                href: "https://s3.us-east-1.amazonaws.com/env-benevity-donation-service-private/bulk/550e8400-e29b-41d4-a716-446655440000/donations.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=...&X-Amz-SignedHeaders=host&x-id=GetObject"
                            updatedAt: '2021-06-08T18:28:14.630Z'
            401:
              $ref: '#/components/responses/Unauthorized'
            403:
              $ref: '#/components/responses/Forbidden'
            404:
              $ref: '#/components/responses/NotFound'
            500:
              $ref: '#/components/responses/InternalServerError'
            default:
              description: Unexpected Error.
              content: {}
      security:
        - Oauth2:
            - benevity/api
  /search/causes:
    get:
      security:
        - Oauth2:
          - benevity/api
        - bearerAuth:
          - token
      tags:
        - Search
      operationId: causeSearch
      summary: Search for causes.
      description: Search for active causes and their projects.
      parameters:
        - name: q
          in: query
          description: >
            A string (e.g. an end user's search box input) containing one or more search keywords.


            Note that special search syntax in the form of `field_name:field_value` may be used for some fields. The following fields are
            currently supported.

            * `id`

            * `parent_id`


            Additional details are available in the response descriptions of these fields.
          schema:
            type: string
            example: cat shelters
        - name: page
          in: query
          description: Which page of the search results to show.
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
            example: 2
        - name: page_size
          in: query
          description: The number of search results to return per page.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 25
            example: 50
        - $ref: '#/components/parameters/searchLocation'
        - $ref: '#/components/parameters/country'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/visibility'
        - $ref: '#/components/parameters/rulesetTag'
        - $ref: '#/components/parameters/foundation'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/autocorrect'
        - $ref: '#/components/parameters/includeChildren'
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                description: Search causes Jsonapi response
                type: object
                required:
                  - data
                  - meta
                  - links
                properties:
                  data:
                    description: Cause search result data.
                    type: array
                    items:
                      description: Cause returned from the search request.
                      type: object
                      required:
                        - type
                        - id
                        - attributes
                      properties:
                        type:
                          description: The type of result.
                          type: string
                          enum:
                            - causes
                        id:
                          description: >-
                            Unique identifier of a project or cause. The project identifier is the cause identifier appended with a
                            forward-slash '/' separator and the project's 10-digit alphanumeric identifier.

                            Note that special search syntax may be used on this field. For example, supplying "id:124-1234567890/PR0J3KC0D3"
                            as the search term will ensure only the cause or project with the id "124-1234567890/PR0J3KC0D3" is returned.
                          type: string
                          example: 124-1234567890/PR0J3KC0D3
                        attributes:
                          description: >-
                            Details of the cause. Causes which contain parent_name and parent_id details are considered cause projects.
                            Cause projects are created by parent organizations to focus on specific goals.
                          type: object
                          required:
                            - name
                            - visibility
                            - status
                          properties:
                            parent_id:
                              description: >-
                                Unique identifier of the result's parent cause. The identifier is the cause's government number prefixed by
                                the ISO 3166-1 numeric country code it is registered in. This field will only be returned for cause
                                projects.

                                Note that special search syntax may be used on this field. For example, supplying "parent_id:124-1234567890"
                                as the search term will ensure only projects with parent_id "124-1234567890" are returned.
                              type: string
                              example: 124-1234567890
                            parent_name:
                              description: Name of the result's parent cause. This field will only be returned for cause projects.
                              type: string
                              example: Direct Relief
                            parent_logo:
                              description: URL of the result's parent cause logo. This field will only be returned for cause projects.
                              type: string
                              example: 'https://my-cdn.com/150x150/public/clogos/cause_logo.png'
                            name:
                              description: Name of the cause.
                              type: string
                              example: Australian Wildfires
                            description:
                              description: A short text extract from the cause description.
                              type: string
                              example: >-
                                Direct Relief is coordinating with a number of Australian agencies and organizations – including the
                                Department of Health, the Department of Environment, Land, Water, and Planning ...
                            city:
                              description: The name of the city associated with the result's project or cause.
                              type: string
                              example: Melbourne
                            state:
                              description: 'The state, province or region associated with the result.'
                              type: object
                              required:
                                - name
                                - code
                              properties:
                                name:
                                  description: 'The name of the state, province or region.'
                                  type: string
                                  example: Victoria
                                code:
                                  description: 'The ISO 3166-2 standard code of the state, province or region.'
                                  type: string
                                  pattern: '[A-Z]{2}-[A-Z0-9]{1,3}'
                                  example: AU-VIC
                            country:
                              description: The country associated with the result.
                              type: object
                              required:
                                - name
                                - code
                              properties:
                                name:
                                  description: The name of the country.
                                  type: string
                                  example: Australia
                                code:
                                  description: The ISO 3166 standard code of the country.
                                  type: string
                                  pattern: '[A-Z]{2}'
                                  example: AU
                            geo_coordinates:
                              description: The Geo-Coordinates of the result.
                              type: object
                              required:
                                - latitude
                                - longitude
                              properties:
                                latitude:
                                  description: The latitude coordinates
                                  type: string
                                  example: '-37.840935'
                                longitude:
                                  description: The longitude coordinates
                                  type: string
                                  example: '144.946457'
                              additionalProperties: false
                            donation:
                              description: The Donation statistics of the result.
                              type: object
                              properties:
                                donor_count:
                                  description: >-
                                    The approximate number of unique user donors that have donated to this cause. It is a long integer in
                                    string format
                                  type: string
                                  example: '1500'
                                trending_score:
                                  description: |-
                                    The discrete trending score from 1 to 10.
                                    More trending cause will get a higher score.
                                  type: integer
                                  example: 9
                              additionalProperties: false
                            distance:
                              description: Kilometer distance from search location to result location.
                              type: number
                              example: '15.37'
                            logo:
                              description: 'URL of the project or cause logo. Images can be png, gif, or jpeg, and are of dimension 150x150.'
                              type: string
                              example: 'https://my-cdn.com/150x150/public/plogos/project_logo.png'
                            categories:
                              description: >-
                                Causes fall into categories which can be filtered on using this parameter. The exact category and
                                subcategory codes to filter on can be found within the response facets.
                              type: array
                              items:
                                type: object
                                properties:
                                  category_name:
                                    description: The name of the category
                                    type: string
                                    example: Human Services
                                  category_code:
                                    description: The NTEE code of the category
                                    type: string
                                    example: P
                                  subcategory_name:
                                    description: The name of the subcategory
                                    type: string
                                    example: Human Services - Multipurpose and Other N.E.C.
                                  subcategory_code:
                                    description: The NTEE code of the subcategory
                                    type: string
                                    example: P99
                            visibility:
                              description: >-
                                The visibility of a result is the highest level action that can be taken on it. For example a visibility of
                                `donate` will guarantee that the result can be donated to, while a visibility of `nominate` means the most
                                that can be done is a nomination. See the request's visibility parameter for more information.

                                * `donate` - You may donate to this result.

                                * `program` - This result is part of your program.

                                * `nominate` - It is undetermined whether this result is in your program, but it can be nominated to
                                determine its eligibility.

                                * `ineligible` - This result is excluded from your company's program.

                                * `inactive` - This result is inactive.
                              type: string
                              enum:
                                - donate
                                - program
                                - nominate
                                - ineligible
                                - inactive
                            status:
                              description: Detailed reporting behind the result's visibility status.
                              type: object
                              required:
                                - program
                                - routing
                                - payment
                              properties:
                                program:
                                  description: >-
                                    Program eligibility of this cause is determined by your company's filter rules. An undetermined state
                                    means that the cause is missing information that will definitively make it eligible or ineligible for
                                    your program. The `tag` request parameter can specify what filter rules are considered.
                                  type: string
                                  enum:
                                    - eligible
                                    - undetermined
                                    - ineligible
                                routing:
                                  description: >-
                                    Routing eligibility is determined by whether donations can be routed to this cause through the
                                    foundations registered with your company. The `foundation` request parameter can specify what
                                    foundations are considered.
                                  type: string
                                  enum:
                                    - eligible
                                    - undetermined
                                payment:
                                  description: >-
                                    The eligibility status of this cause based on its payment type. Unless your company has this setting
                                    overridden, any causes outside of US and Canada without an EFT or PAYPAL payment type will be marked as
                                    undetermined.
                                  type: string
                                  enum:
                                    - eligible
                                    - undetermined
                            snippets:
                              description: >-
                                Snippets are fragments of text that reveal the contextual relevance between the search terms and the search
                                results. Matching search terms are surrounded by emphasis tags <em> </em>. The following categories of
                                snippets are available: title, cause, body, tag, contact and location.
                              type: object
                              properties:
                                title:
                                  description: A highlighted fragment of text that matches the user's search terms in the result's name.
                                  type: string
                                  example: Australian <em>Wildfires</em>
                                cause:
                                  description: >-
                                    A highlighted fragment of text that matches the user's search term in cause alternative names or
                                    identifiers.
                                  type: string
                                  example: <em>124-1234567890</em>
                                body:
                                  description: A highlighted fragment of text that matches the user's search terms in the cause description.
                                  type: string
                                  example: Direct <em>Relief</em> is coordinating with a number of Australian agencies and organizations ...
                                tag:
                                  description: A highlighted fragment of text that matches the user's search terms in a cause's tags.
                                  type: string
                                  example: <em>Human</em> Services
                                contact:
                                  description: A highlighted fragment of text that matches the user's search terms in a cause's contact details.
                                  type: string
                                  example: <em>www.directrelief.org</em>
                                location:
                                  description: A highlighted fragment of text that matches the user's search terms in the cause location details.
                                  type: string
                                  example: '<em>Melbourne</em>, Victoria, Australia'
                  links:
                    description: Self and the pagination links for this search query
                    type: object
                    allOf:
                      - required:
                          - self
                        properties:
                          self:
                            description: The relative URL path of the current search query
                            type: string
                            example: /search/causes?q=*&page=3
                      - description: Pagination links
                        type: object
                        properties:
                          first:
                            description: The relative URL path of the first result page; if results are not empty
                            type: string
                            example: /search/causes?q=*&page=1
                          prev:
                            description: The relative URL path of the previous result page; if current page is not the first page
                            type: string
                            example: /search/causes?q=*&page=2
                          next:
                            description: The relative URL path of the next result page; if current page is not the last page
                            type: string
                            example: /search/causes?q=*&page=4
                          last:
                            description: The relative URL path of the last result page; if results are not empty
                            type: string
                            example: /search/causes?q=*&page=10
                  meta:
                    description: Meta info for this search query
                    type: object
                    properties:
                      search_information:
                        description: Meta info of this search response
                        type: object
                        required:
                          - total_results
                        properties:
                          total_results:
                            description: The total number of results found for this search query.
                            type: integer
                            example: 20
                          showing_results_for:
                            description: >-
                              The q string that was used for generating current search results. If this value is equal to
                              spell_check_suggestion, then there were no results for the original search term and a spell check suggested
                              query was used instead.
                            type: string
                            example: united states
                          spell_check_suggestion:
                            description: The spell check suggested query string.
                            type: string
                            example: united states
                      search_parameters:
                        description: A reiteration of parameters used for this search.
                        type: object
                        example:
                          q: wildlife
                          page: 2
                      facets:
                        description: Result of the supported faceting fields.
                        type: object
                        properties:
                          country:
                            description: Country facet buckets
                            type: array
                            items:
                              $ref: >-
                                #/paths/~1search~1causes/get/responses/200/content/application~1vnd.api%2Bjson/schema/properties/meta/properties/facets/properties/state/items
                            example:
                              - val: AU
                                label: Australia
                                count: 5
                          state:
                            description: State facet buckets
                            type: array
                            items:
                              description: 'Values of the facet dimension that are present in the results, summarized by how many times they appear.'
                              type: object
                              required:
                                - val
                                - count
                              properties:
                                val:
                                  description: >-
                                    A value of the facet aspect/dimension. Typically, this value should be used for any corresponding
                                    filters.
                                  type: string
                                label:
                                  description: The human-friendly display label of the facet aspect/dimension.
                                  type: string
                                count:
                                  description: The number of results that have this facet aspect value.
                                  type: integer
                            example:
                              - val: AU-VIC
                                label: Victoria
                                count: 5
                          categories:
                            description: Categories facet buckets
                            type: array
                            items:
                              $ref: >-
                                #/paths/~1search~1causes/get/responses/200/content/application~1vnd.api%2Bjson/schema/properties/meta/properties/facets/properties/state/items
                            example:
                              - val: P
                                label: Human Services
                                count: 5
                          subcategories:
                            description: >-
                              Subcategories facet buckets.

                              Note: Some categories have common subcategory labels such as `Alliance/Advocacy Organizations` although their
                              codes are unique.
                            type: array
                            items:
                              $ref: >-
                                #/paths/~1search~1causes/get/responses/200/content/application~1vnd.api%2Bjson/schema/properties/meta/properties/facets/properties/state/items
                            example:
                              - val: P99
                                label: Human Services - Multipurpose and Other N.E.C.
                                count: 5
        '400':
          description: Bad Request
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  errors:
                    description: List of errors that failed the search request.
                    type: array
                    items:
                      description: Details of an error
                      type: object
                      required:
                        - code
                        - title
                      properties:
                        code:
                          description: An application-specific error code.
                          type: string
                          example: validation
                        title:
                          description: A human-readable description of the problem.
                          type: string
                          example: One or more validation errors were present in the request.
                        detail:
                          description: A human-readable message providing more details about the error.
                          type: string
                          example: Value must be greater than 0
                        source:
                          description: The source of the error.
                          type: object
                          required:
                            - parameter
                          properties:
                            parameter:
                              description: The request parameter (or header) that caused the error.
                              type: string
                              example: page_size
              example:
                errors:
                  - code: validation
                    title: One or more validation errors were present in the request.
                    detail: Invalid visibility parameter.
                    source:
                      parameter: visibility
        '500':
          description: Internal Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1search~1causes/get/responses/400/content/application~1vnd.api%2Bjson/schema'
              example:
                errors:
                  - code: internal_server_error
                    title: An unknown internal error occurred.
  /search/givingopportunities:
    get:
      security:
        - Oauth2:
            - benevity/api
      tags:
        - Search
      operationId: givingOpSearch
      summary: Search for giving opportunities.
      description: Search for giving opportunities. Only opportunities made public and not closed will be returned.
      parameters:
        - name: q
          in: query
          description: A string (e.g. an end user's search box input) containing one or more search keywords.
          schema:
            type: string
            example: cat shelters
        - name: filter
          in: query
          description: >-
            A collection of filters restricting the set of results returned. If multiple filters are present, they will be "AND"-ed
            together.
          style: deepObject
          explode: true
          schema:
            type: object
            properties:
              tags:
                type: string
                description: >-
                  Tags provide an additional taxonomy for opportunities. When used as filters in search, only returns opportunities that
                  have at least one of the tags specified. This parameter can be used multiple times for different values. The values will
                  be OR'd together.
                items:
                  type: string
              product_area:
                type: string
                description: >-
                  When used as filter in search, only returns opportunities matching the product area to which the creators of the
                  opportunities belong to. This parameter can be used multiple times for different values. The values will be OR'd together.
                items:
                  type: string
              office_location:
                type: string
                description: >-
                  When used as filter in search, only returns opportunities matching the office location of the opportunities creators. This
                  parameter can be used multiple times for different values. The values will be OR'd together.
                items:
                  type: string
        - name: autocorrect
          in: query
          description: >-
            When set to true, will do a second search using the spell check suggestion if there are no results for the original search term.
            Default is false(won't do a second search).
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          description: Which page of the search results to show.
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
            example: 2
        - name: page_size
          in: query
          description: The number of search results returned per page.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 25
            example: 50
        - name: search_location
          in: query
          description: >-
            The origin point of the search, expressed as `latitude,longitude`. Opportunities physically closer to this point will be ranked
            higher in the results. Latitude must be between -90 and 90, and longitude must be between -180 and 180.
          schema:
            type: string
            example: '51.051651,-114.050880'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  giving_opportunities:
                    type: array
                    items:
                      $ref: '#/components/schemas/GivingOpportunity'
                  facets:
                    type: array
                    description: >-
                      Faceting is an extension of traditional filtering. In this section, multiple filter options are provided, one for each
                      relevant (and pre-defined) aspect of the entities being searched. This information can be added to a search results
                      page to allow users to quickly narrow down their initial result set.
                    items:
                      $ref: '#/components/schemas/Facet'
                  autocorrect:
                    type: boolean
                    description: echo back the autocorrect request parameter
                  page:
                    type: integer
                    format: int32
                    description: The page of results that was returned in this response (starts at 1).
                  page_size:
                    type: integer
                    format: int32
                    description: Number of results returned per page.
                  total:
                    type: integer
                    format: int32
                    description: Total number of results found for this search query.
                  search_information:
                    $ref: '#/components/schemas/SearchInformation'
        '400':
          $ref: '#/components/responses/BadRequestDeprecated'
        '404':
          $ref: '#/components/responses/NotFoundDeprecated'
        '500':
          $ref: '#/components/responses/InternalServerErrorDeprecated'
  /search/volunteeropportunities:
    get:
      security:
        - Oauth2:
            - benevity/api
      tags:
        - Search
      operationId: volOpSearch
      summary: Search for volunteer opportunities.
      description: Search for volunteer opportunities. Only opportunities made public will be returned.
      parameters:
        - name: q
          in: query
          description: A string (e.g. an end user's search box input) containing one or more search keywords.
          schema:
            type: string
            example: cat shelters
        - name: filter
          in: query
          description: >-
            A collection of filters restricting the set of results returned. If multiple filters are present, they will be "AND"-ed
            together.
          style: deepObject
          explode: true
          schema:
            type: object
            properties:
              temporal_type:
                type: string
                description: Only return opportunities that continue indefinitely or have a set start/end time.
                enum:
                  - ongoing
                  - time_bounded
              ends_after:
                type: string
                description: Only return opportunities ending on or after this time that are available for signup.
                format: date-time
                example: '2019-02-01T21:00:00+00:00'
              starts_before:
                type: string
                description: Only return opportunities starting on or before this time that are available for signup.
                format: date-time
                example: '2019-02-05T21:00:00+00:00'
              minimum_open_spots:
                type: integer
                description: >-
                  Only return opportunities that have at least one shift that have open spots that are equal to or greater than the given
                  minimum.
              has_location:
                type: boolean
                description: 'Only return opportunities that have, or do not have, a physical location set.'
              skills:
                type: string
                description: >-
                  Only return opportunities with at least one of the volunteering skills specified. Possible values for `skills` can be
                  found in the response, under `facets`. This parameter can be used multiple times for different values. The values will be
                  OR'd together.
                items:
                  type: string
              interests:
                type: string
                description: >-
                  Only return opportunities with at least one of the volunteering interests specified. Possible values for `interests` can
                  be found in the response, under `facets`. This parameter can be used multiple times for different values. The values will
                  be OR'd together.
                items:
                  type: string
              characteristics:
                type: string
                description: >-
                  Only return opportunities with at least one of the volunteer opportunity characteristics specified. Possible values for
                  `characteristics` can be found in the response, under `facets`. This parameter can be used multiple times for different
                  values. The values will be OR'd together.
                items:
                  type: string
        - name: autocorrect
          in: query
          description: >-
            When set to true, will do a second search using the spell check suggestion if there are no results for the original search term.
            Default is false(won't do a second search).
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          description: Which page of the search results to show.
          schema:
            type: integer
            format: int32
            default: 1
            example: 2
        - name: page_size
          in: query
          description: The number of search results returned per page.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 25
            example: 50
        - name: search_location
          in: query
          description: >-
            The origin point of the search, expressed as `latitude,longitude`. Opportunities physically closer to this point will be ranked
            higher in the results. Latitude must be between -90 and 90, and longitude must be between -180 and 180.
          schema:
            type: string
            example: '51.051651,-114.050880'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  volunteer_opportunities:
                    type: array
                    items:
                      $ref: '#/components/schemas/Volop'
                  facets:
                    type: array
                    description: >-
                      Faceting is an extension of traditional filtering. In this section, multiple filter options are provided, one for each
                      relevant (and pre-defined) aspect of the entities being searched. This information can be added to a search results
                      page to allow users to quickly narrow down their initial result set.
                    items:
                      $ref: '#/components/schemas/Facet'
                  autocorrect:
                    type: boolean
                    description: echo back the autocorrect request parameter
                  page:
                    type: integer
                    format: int32
                  page_size:
                    type: integer
                    format: int32
                  total:
                    type: integer
                    format: int32
                  search_information:
                    $ref: '#/components/schemas/SearchInformation'
        '400':
          $ref: '#/components/responses/BadRequestDeprecated'
        '404':
          $ref: '#/components/responses/NotFoundDeprecated'
        '500':
          $ref: '#/components/responses/InternalServerErrorDeprecated'
  /causes/{id}:
    get:
      security:
        - Oauth2:
            - benevity/api
        - bearerAuth:
            - token
      summary: Returns detailed information about a cause.
      operationId: GetCauseDetails
      description: Returns detailed information about a cause.
      tags:
        - Causes API
      parameters:
        - name: id
          in: path
          description: The unique resource identifier of the target cause
          required: true
          schema:
            type: string
      responses:
        200:
          description: The successful response of the cause details request.
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/GetCauseDetailsResponse"
              examples:
                840-99999999:
                  value:
                    data:
                      type: causes
                      id: 840-99999999
                      attributes:
                        name: Charitable Giving Organization
                        government_name: Charitable Giving Organization Corp.
                        phone: (001) 123-4567
                        website: 'https://benevity.com/'
                        social:
                          facebook: 'http://www.facebook.com/benevity'
                          twitter: Benevity
                          rss: 'https://www.benevity.com/rss/feeds'
                        address:
                          street: 1234 Random Ave NW
                          line2: Suite 123
                          line3: Unit 99
                          city: Washington
                          postcode: '99999'
                          region:
                            name: Wisconsin
                            alpha_code: WI
                          country:
                            numeric_code: '840'
                            alpha_code: USA
                            name: United States
                        caption: Charitable Giving Organization works to raise money for non-profits across the world.
                        description: Charitable Giving Organization is a charity fundraising web site that gives social entrepreneurs and non-profits from anywhere in the world a chance to raise the money that they need to improve their communities.
                        active: true
                        disbursable: true
                        tags:
                          - type: public
                            value: aid
                        categories:
                          - category_name: Health - General and Rehabilitative
                            category_code: E
                            subcategory_name: Health - General and Rehabilitative N.E.C.
                            subcategory_code: '99'
                        certification:
                          status: certified
                          effective_timestamp: '2022-09-22T15:32:53+00:00'
                          expiry_timestamp: '2023-09-22T15:32:53+00:00'
                        claimed: '2021-11-26T14:18:11+00:00'
                        owner_verified:
                          status: true
                          timestamp: '2021-12-02T01:47:36+00:00'
                        logos:
                          - size: 400x400
                            url: 'https://logos.benevity.org/400x400/public/clogos/840-99999999.png'
                124-119219814RR0001:
                  value:
                    data:
                      type: causes
                      id: 124-119219814RR0001
                      attributes:
                        name: CANADIAN RED CROSS / CROIX-ROUGE CANADIENNE
                        government_name: THE CANADIAN RED CROSS SOCIETY / LA SOCIETE CANADIENNE DE LA CROIX-ROUGE
                        phone: 1 (800) 418-1111
                        website: www.redcross.ca
                        social:
                          facebook: 'http://www.facebook.com/canadianredcross'
                          twitter: redcrosscanada
                          rss: 'https://www.redcross.ca/about-us/red-cross-stories?rss=Canadian-Red-Cross-Stories'
                        address:
                          street: '400 Cooper Street, Suite 8000,'
                          city: Ottawa
                          postcode: K2P 2H8
                          region:
                            name: Ontario
                            alpha_code: 'ON'
                          country:
                            numeric_code: '124'
                            alpha_code: CAN
                            name: Canada
                        caption: We help people and communities in Canada and around the world in times of need and support them in strengthening their resilience.
                        description: |-
                          *** Le français suit***

                          For more than 125 years, the Canadian Red Cross has provided help to those in need...
                        active: true
                        disbursable: true
                        tags:
                          - type: public
                            value: aid
                          - type: public
                            value: relief
                          - type: public
                            value: emergency response
                        categories:
                          - category_name: Health - General and Rehabilitative
                            category_code: E
                            subcategory_name: Health - General and Rehabilitative N.E.C.
                            subcategory_code: '99'
                        certification:
                          status: certified
                          effective_timestamp: '2022-09-22T15:32:53+00:00'
                          expiry_timestamp: '2023-09-22T15:32:53+00:00'
                        claimed: '2021-11-26T14:18:11+00:00'
                        owner_verified:
                          status: true
                          timestamp: '2021-12-02T01:47:36+00:00'
                        logos:
                          - size: 400x400
                            url: 'https://logos.benevity.org/400x400/public/clogos/124-119219814RR0001.jpg'
                          - size: 50x50
                            url: 'https://logos.benevity.org/50x50/public/clogos/124-119219814RR0001.jpg'
                          - size: 300x300
                            url: 'https://logos.benevity.org/300x300/public/clogos/124-119219814RR0001.jpg'
                          - size: 150x150
                            url: 'https://logos.benevity.org/150x150/public/clogos/124-119219814RR0001.jpg'
        401:
          $ref: "#/components/responses/Unauthorized"
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: "#/components/responses/InternalServerError"
        503:
          $ref: "#/components/responses/ServiceUnavailable"
        default:
          description: Unexpected Error.
          content: {}
  '/causes/categories':
    get:
      tags:
        - Causes API
      security:
        - Oauth2:
            - benevity/api
      summary: Returns the list of cause categories
      operationId: GetCauseCategoryList
      description: Returns list of cause categories.
      parameters:
        - name: countryCode
          in: query
          description: The country code of the categories to return.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The successful response of the list of categories.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetCauseCategoryListResponse'
              examples:
                "124":
                  value:
                    data:
                      - id: "01"
                        type: categories
                        attributes:
                          name: Mental Health and Crisis Intervention
                          subcategories:
                            - id: "01"
                              name: Mental Health Crisis Intervention N.E.C.

                            - id: "57"
                              name: Counseling Support Groups

                      - id: "02"
                        type: categories
                        attributes:
                          name: Public Safety Disaster Preparedness and Relief
                          subcategories:
                            - id: "02"
                              name: Fund Raising and/or Fund Distribution

                      - id: "99"
                        type: categories
                        attributes:
                          name: Unknown
                          subcategories:
                            - id: "99"
                              name: Unknown

        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected Error.
          content: { }

  '/causes/regions':
    get:
      tags:
        - Causes API
      security:
        - Oauth2:
            - benevity/api
        - bearerAuth:
            - token
      summary: Returns the list of geographical regions
      operationId: GetGeographicalRegionList
      description: Returns list of geographical regions.
      parameters:
        - name: countryCode
          in: query
          description: The country code of the geographical region to return.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The successful response of the list of geographical region.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetGeographicalRegionResponse'
              examples:
                "124":
                  value:
                    data:
                      - id: 245S7W3NGH
                        type: regions
                        attributes:
                          code: DC
                          name: Canada
                          subcategory: COUNTRY

                      - id: 3B1MDS51TZ
                        type: regions
                        attributes:
                          code: AB
                          name: Alberta
                          subcategory: STATE

                      - id: 3AGL2HC0Q3
                        type: regions
                        attributes:
                          code: BC
                          name: British Columbia
                          subcategory: STATE

                      - id: 3C5Q29R41R
                        type: regions
                        attributes:
                          code: MB
                          name: Manitoba
                          subcategory: STATE

                      - id: 3DUU2247DD
                        type: regions
                        attributes:
                          code: NB
                          name: New Brunswick
                          subcategory: STATE
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          description: Unexpected Error.
          content: { }
  /causes-ptl-api/api/v1/profile/organizations/{id}:
    get:
      tags:
        - Organization
      summary: Retrieve nonprofit organization
      security:
        - bearerAuth: [ ]
      operationId: getOrganization
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrganizationDto'
    patch:
      tags:
        - Organization
      summary: Update nonprofit organization
      security:
        - bearerAuth: [ ]
      operationId: updateOrganization
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/OrganizationDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrganizationDto'
components:
  schemas:
    OrganizationDto:
      type: object
      properties:
        registeredName:
          maxLength: 256
          minLength: 0
          type: string
        displayName:
          maxLength: 256
          minLength: 0
          type: string
        description:
          maxLength: 10000
          minLength: 0
          type: string
        mission:
          maxLength: 10000
          minLength: 0
          type: string
        foundingYear:
          type: integer
          format: int32
        governmentClassification:
          maxLength: 256
          minLength: 0
          type: string
        addressLine1:
          maxLength: 256
          minLength: 0
          type: string
        addressLine2:
          maxLength: 256
          minLength: 0
          type: string
        addressLine3:
          maxLength: 256
          minLength: 0
          type: string
        city:
          maxLength: 256
          minLength: 0
          type: string
        state:
          maxLength: 256
          minLength: 0
          type: string
        postalCode:
          maxLength: 24
          minLength: 0
          type: string
        country:
          type: string
        email:
          maxLength: 96
          minLength: 0
          type: string
        website:
          maxLength: 256
          minLength: 0
          type: string
        phone:
          maxLength: 96
          minLength: 0
          type: string
        referenceIds:
          $ref: '#/components/schemas/JSONObject'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/ContactDto'
        funders:
          type: array
          items:
            $ref: '#/components/schemas/FunderDto'
        financials:
          type: array
          items:
            $ref: '#/components/schemas/FinancialDto'
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/BudgetDto'
        partnerships:
          type: array
          items:
            $ref: '#/components/schemas/PartnershipDto'
        keyPeople:
          type: array
          items:
            $ref: '#/components/schemas/KeyPersonDto'
        logo:
          $ref: '#/components/schemas/MediaDto'
        createdAt:
          type: string
          format: date-time
        createdBy:
          maxLength: 96
          minLength: 0
          type: string
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          maxLength: 96
          minLength: 0
          type: string
        deletedAt:
          type: string
          format: date-time
        deletedBy:
          maxLength: 96
          minLength: 0
          type: string
    PartnershipDto:
      type: object
      properties:
        id:
          type: string
        type:
          maxLength: 256
          minLength: 0
          type: string
        name:
          maxLength: 256
          minLength: 0
          type: string
        purpose:
          maxLength: 10000
          minLength: 0
          type: string
    MediaDto:
      type: object
      properties:
        id:
          type: string
        type:
          maxLength: 64
          minLength: 0
          type: string
        name:
          maxLength: 256
          minLength: 0
          type: string
        description:
          maxLength: 10000
          minLength: 0
          type: string
        s3Key:
          maxLength: 256
          minLength: 0
          type: string
        createdAt:
          type: string
          format: date-time
        createdBy:
          maxLength: 96
          minLength: 0
          type: string
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          maxLength: 96
          minLength: 0
          type: string
    FunderDto:
      type: object
      properties:
        id:
          type: string
        name:
          maxLength: 256
          minLength: 0
          type: string
        currency:
          maxLength: 3
          minLength: 3
          type: string
        amount:
          type: integer
          format: int32
    BudgetDto:
      type: object
      properties:
        id:
          type: string
        name:
          maxLength: 256
          minLength: 0
          type: string
        currency:
          maxLength: 3
          minLength: 3
          type: string
        amount:
          type: integer
          format: int32
        periodStart:
          type: string
          format: date-time
        periodEnd:
          type: string
          format: date-time
    ContactDto:
      type: object
      properties:
        id:
          type: string
        firstName:
          maxLength: 256
          minLength: 0
          type: string
        lastName:
          maxLength: 256
          minLength: 0
          type: string
        title:
          maxLength: 256
          minLength: 0
          type: string
        phone:
          maxLength: 96
          minLength: 0
          type: string
        email:
          maxLength: 96
          minLength: 0
          type: string
        isPrimary:
          type: boolean
    KeyPersonDto:
      type: object
      properties:
        id:
          type: string
        firstName:
          maxLength: 256
          minLength: 0
          type: string
        lastName:
          maxLength: 256
          minLength: 0
          type: string
        title:
          maxLength: 256
          minLength: 0
          type: string
        phone:
          maxLength: 96
          minLength: 0
          type: string
        email:
          maxLength: 96
          minLength: 0
          type: string
        employer:
          maxLength: 256
          minLength: 0
          type: string
        tenure:
          maxLength: 32
          minLength: 0
          type: string
        socialHandles:
          $ref: '#/components/schemas/JSONObject'
    JSONObject:
      type: object
      properties:
        empty:
          type: boolean
    FinancialDto:
      type: object
      properties:
        id:
          type: string
        fiscalYearStart:
          type: string
          format: date
        fiscalYearEnd:
          type: string
          format: date
        currency:
          maxLength: 3
          minLength: 3
          type: string
        revenueTotal:
          type: integer
          format: int32
        revenueContributionsGrants:
          type: integer
          format: int32
        revenueProgramService:
          type: integer
          format: int32
        revenueInvestment:
          type: integer
          format: int32
        revenueOther:
          type: integer
          format: int32
        expensesTotal:
          type: integer
          format: int32
        expensesGrants:
          type: integer
          format: int32
        expensesMembers:
          type: integer
          format: int32
        expensesEmployees:
          type: integer
          format: int32
        expensesFees:
          type: integer
          format: int32
        expensesOther:
          type: integer
          format: int32
        assetsTotal:
          type: integer
          format: int32
        liabilityTotal:
          type: integer
          format: int32
    Address:
      type: object
      properties:
        address_name:
          type: string
          maxLength: 255
          description: The name of the location.
          example: Benevity Calgary HQ
        address_street:
          type: string
          maxLength: 255
          description: The street address.
          example: '611 Meredith Rd NE #700'
        address_city:
          type: string
          maxLength: 255
          description: The name of the city.
          example: Calgary
        address_state:
          type: string
          maxLength: 255
          description: The state, province, or region. May be a full name or an abbreviation.
          example: Alberta
        address_postcode:
          type: string
          maxLength: 255
          description: The postal code of the mailing address (format varies by country).
          example: T2E 2W5
        address_country:
          type: string
          maxLength: 255
          description: Name of the country in English.
          example: Canada
    Amount:
      required:
        - currencyCode
        - totalAmountCents
      type: object
      properties:
        totalAmountCents:
          minimum: 1
          type: number
          description:
            The dollar amount in cents for the entire donation. This is
            the amount charged to the credit card
          format: int64
        currencyCode:
          maxLength: 3
          minLength: 3
          type: string
          description: The currency code. Must be a valid ISO-4217 currency code
    ApplePayPaymentMethod:
      type: object
      allOf:
        - '$ref': '#/components/schemas/PaymentMethod'
    BulkIntentAttributes:
      type: object
      required:
        - type
        - id
        - status
        - createdAt
      properties:
        type:
          type: string
          example: 'bulkDonationIntent'
        id:
          $ref: '#/components/schemas/JSONAPIId'
        status:
          $ref: '#/components/schemas/Status'
        createdAt:
          type: string
          example: '2021-06-08T18:18:14.630Z'
        updatedAt:
          type: string
          example: '2021-06-08T18:18:24.630Z'
        expiresAt:
          type: string
          example: '2021-06-08T18:28:14.630Z'
        fields:
            $ref: '#/components/schemas/Fields'
        errors:
            type: array
            items:
              $ref: '#/components/schemas/ErrorObject'
    BulkIntentResponseAttributes:
      allOf:
        - $ref: '#/components/schemas/JSONAPIRelationshipObject'
        - type: object
          required:
            - type
            - id
            - status
            - createdAt
          properties:
            type:
              type: string
              example: 'bulkDonationIntent'
            id:
              $ref: '#/components/schemas/JSONAPIId'
            status:
              $ref: '#/components/schemas/Status'
            createdAt:
              type: string
              example: '2021-06-08T18:18:14.630Z'
            updatedAt:
              type: string
              example: '2021-06-08T18:18:24.630Z'
            expiresAt:
              type: string
              example: '2021-06-08T18:28:14.630Z'
            errors:
              type: array
              items:
                $ref: '#/components/schemas/ErrorObject'
    BulkIntentResponseObject:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          type: string
          example: bulkDonationIntent
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
        attributes:
          $ref: '#/components/schemas/BulkIntentAttributes'
    BenevityException:
      type: object
      properties:
        code:
          type: integer
          format: int32
          default: 111
        message:
          type: string
          default: Generic error
        details:
          type: string
          default: An error occurred in processing
      example:
        code: 100
        message: Generic Error
        details: An error occurred in processing the request
    CardHolder:
      required:
        - email
        - firstName
        - lastName
      type: object
      properties:
        firstName:
          maxLength: 100
          type: string
          description: First Name.
          default: Ralphy
        lastName:
          maxLength: 100
          type: string
          description: Last Name.
          default: Wiggum
        email:
          maxLength: 100
          minLength: 3
          type: string
          description: Email Address. Required field
          format: email
          default: ralphwiggum@email.com
        country:
          maxLength: 2
          minLength: 2
          type: string
          description: Country code.
          default: ca
        address:
          maxLength: 100
          type: string
          description: Address information.
          default: 55555 Evergreen Terrace
        address2:
          maxLength: 42
          minLength: 2
          type: string
          description: Address2 information
          default: Apt 301
        city:
          maxLength: 42
          minLength: 2
          type: string
          description: City. Not required
          default: Springfield
        provinceState:
          maxLength: 2
          minLength: 2
          type: string
          description: Province or State depending upon location
          default: BC
        postalZip:
          maxLength: 20
          type: string
          description: Postal code or zip depending upon location
          default: '90210'
      example:
        firstName: Ralph
        lastName: Wiggum
        email: ralphwiggum@email.com
        country: ca
        address: Evergreen Terrace
        address2: Apt 301
        provinceState: BC
        postalZip: 90210
        city: Springfield
    CauseAddress:
      type: object
      description: The cause's address.
      properties:
        street:
          type: string
          description: The cause's street information.
          example: 1234 Random Ave NW
        line2:
          type: string
          description: The cause's additional street information.
          example: Suite 123
        line3:
          type: string
          description: The cause's additional street information.
          example: Unit 99
        city:
          type: string
          description: The cause's city name.
          example: Washington
        postcode:
          type: string
          description: The cause's postcode.
          example: '99999'
        region:
          $ref: '#/components/schemas/CauseAddressRegion'
        country:
          $ref: '#/components/schemas/CauseAddressCountry'
    CauseAddressCountry:
      type: object
      description: The cause's country.
      properties:
        numeric_code:
          type: string
          description: The numeric code of The cause's country.
        alpha_code:
          type: string
          description: The alpha code of The cause's country.
        name:
          type: string
          description: The cause's country name.
      example:
        numeric_code: '840'
        alpha_code: USA
        name: United States
    CauseAddressRegion:
      type: object
      description: The cause's region information.
      properties:
        name:
          type: string
          description: The cause's region name.
        alpha_code:
          type: string
          description: The cause's region alpha code.
      example:
        name: Wisconsin
        alpha_code: WI
    CauseAttributes:
      type: object
      description: The attributes of the target cause.
      properties:
        name:
          type: string
          description: The cause's name.
          example: Charitable Giving Organization
        government_name:
          type: string
          description: The cause's registered company name.
          example: Charitable Giving Organization Corp.
        phone:
          type: string
          description: The cause's phone number.
          example: (001) 123-4567
        website:
          type: string
          description: The cause's website.
          example: 'https://benevity.com/'
        social:
          $ref: '#/components/schemas/CauseSocialAttribute'
        address:
          $ref: '#/components/schemas/CauseAddress'
        caption:
          type: string
          description: A short description of the cause usually.
          example: Charitable Giving Organization works to raise money for non-profits across the world.
        description:
          type: string
          description: The full description of the cause.
          example: Charitable Giving Organization is a charity fundraising web site that gives social entrepreneurs and non-profits from anywhere in the world a chance to raise the money that they need to improve their communities.
        active:
          type: boolean
          description: Whether the cause is active or inactive.
          example: true
        disbursable:
          type: boolean
          description: Whether funds can be disbursed to the cause or not.
          example: true
        tags:
          type: array
          description: A list of the cause's tags.
          items:
            $ref: '#/components/schemas/CauseTag'
        categories:
          type: array
          description: A list of the cause's categories.
          items:
            $ref: '#/components/schemas/CauseCategory'
        certification:
          $ref: '#/components/schemas/CauseCertification'
        claimed:
          type: string
          description: The date/time that the cause was claimed in ISO-8601 format. Omitted from response if not claimed.
          example: '2021-11-26T14:18:11+00:00'
        owner_verified:
          $ref: '#/components/schemas/CauseOwnerVerified'
        logos:
          type: array
          description: A list of the cause's logos.
          items:
            $ref: '#/components/schemas/CauseLogo'
    CauseCategory:
      type: object
      description: "The cause's category information. Causes are classified using the [NTEE IRS specification.](https://nccs.urban.org/publication/irs-activity-codes)"
      properties:
        category_name:
          type: string
          description: The name of the category.
        category_code:
          type: string
          description: The code of the category.
        subcategory_name:
          type: string
          description: The name of the subcategory.
        subcategory_code:
          type: string
          description: The subcode of the category.
      example:
        category_name: Health - General and Rehabilitative
        category_code: E
        subcategory_name: Health - General and Rehabilitative N.E.C.
        subcategory_code: '99'
    CauseCertification:
      type: object
      description: "The cause's certification information. Describes whether the cause owner has completed the [Self-Certification Declaration.](https://benevity.com/causes)"
      required:
        - status
      properties:
        status:
          type: string
          description: The status of the certification.
        effective_timestamp:
          type: string
          description: The effective date/time of the certification in ISO-8601 format. Omitted from response if not certified.
        expiry_timestamp:
          type: string
          description: The expiry date/time of the certification in ISO-8601 format. Omitted from response if not certified.
      example:
        status: certified
        effective_timestamp: '2022-09-22T15:32:53+00:00'
        expiry_timestamp: '2023-09-22T15:32:53+00:00'
    CauseLogo:
      type: object
      description: A cause's logo image.
      properties:
        size:
          type: string
          description: The size of the cause's logo image.
          example: 400x400
        url:
          type: string
          description: The url of the the cause's logo image.
          example: 'https://logos.benevity.org/400x400/public/clogos/840-99999999.png'
    CauseOwnerVerified:
      type: object
      description: The cause's owner verification information.
      required:
        - status
      properties:
        status:
          type: boolean
          description: The status of the owner verification.
        timestamp:
          type: string
          description: The date/time of the owner verification in ISO-8601 format. Omitted from response if not verified.
      example:
        status: true
        timestamp: '2021-12-02T01:47:36+00:00'
    CauseSocialAttribute:
      type: object
      description: The cause's social media accounts.
      properties:
        facebook:
          type: string
          description: The cause's facebook account url.
        twitter:
          type: string
          description: The cause's twitter name.
        rss:
          type: string
          description: The cause's rss feed url.
      example:
        facebook: 'http://www.facebook.com/benevity'
        twitter: Benevity
        rss: 'https://www.benevity.com/rss/feeds'
    CauseTag:
      type: object
      description: A cause tag.
      properties:
        type:
          type: string
          description: The type of the tag.
        value:
          type: string
          description: The value of the tag.
      example:
        type: public
        value: aid
    CategoryAttributes:
      type: object
      description: A cause category.
      required:
        - name
        - subcategories
      properties:
        name:
          type: string
          description: The category name.
        subcategory:
          type: array
          description: The category subcategories.
          items:
            $ref: '#/components/schemas/Subcategory'
    Subcategory:
      type: object
      description: A geographical region.
      required:
        - id
        - name
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/JSONAPIId'
        name:
          type: string
          description: The subcategory name.
    GeographicalRegionAttributes:
      type: object
      description: A geographical region.
      required:
        - code
        - name
        - subcategory
      properties:
        code:
          type: string
          description: The code of the region.
        name:
          type: string
          description: The name of the region.
        subcategory:
          type: string
          description: The subcategory of the region.
    CreateBulkIntentResponse:
      type: object
      required:
        - data
      properties:
        data:
           $ref: '#/components/schemas/BulkIntentResponseObject'
    CreateDonationResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/DonationResponseObject'
    CreateDonationRequest:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/DonationRequestObject'
    CreditCard:
      type: object
      properties:
        name:
          type: string
          description: A named descriptor for the card
          maxLength: 100
        cardHolder:
          $ref: '#/components/schemas/CardHolder'
    CreditCardPaymentMethod:
      type: object
      allOf:
        - '$ref': '#/components/schemas/PaymentMethod'
        - properties:
            hasTokenizedElsewhere:
              type: boolean
              description: Will be True if there are no cards returned for this merchant account but there are tokenized cards on another merchant account. Used for helpful user message.
              default: false
            savedCards:
              format: array
              items: { $ref: '#/components/schemas/CreditCard' }
    CreditCardTransactionRequest:
      allOf:
        - $ref: '#/components/schemas/Transaction'
        - type: object
          properties:
            merchantAccountId:
              type: string
              description:
                The <b>merchantAccountId</b> of the MerchantAccount used
                for the Transaction
            adapter:
              type: string
              description: The <b>adapter</b> of the request accessing
              default: Adapter.Wpg
            paymentConfig:
              $ref: '#/components/schemas/PaymentConfig'
            cardHolder:
              $ref: '#/components/schemas/CardHolder'
          example:
            creditCardId: card54321
            merchantAccountId: '38486450'
            paymentConfig:
              token: abcde12345
              merchantAccountId: 3A27DYHR3J
              processor: BLUESNAP
            cardHolder:
              firstName: Ralph
              lastName: Wiggum
              email: ralphwiggum@email.com
              country: ca
              address: Evergreen Terrace
              address2: Apt 301
              provinceState: BC
              postalZip: '90210'
              city: Springfield
            adapter: Adapter.Wpg
            transactionReason: user_donation
            amount:
              totalAmountCents: 1060
              currencyCode: USD
            description: $10.50 Donation to VOKRA
            softDescriptor: Benevity
            referenceNumber: hb7ue7s0dn196dfkebm0ulekr2-59f8fe7257fc37.57584560
            locale: en_us
            payerBusinessName: google
            purchaseItems:
              - name: itemname
                action: USERPURCHASECREDITSANDDONATE
                quantity: 1
                itemTotalAmountCents: 1050
                matchCap: 50
                receiptNote: Note
                customReceiptBanner: banner.png
                sharing: false
                sendReceipt: true
                allocations:
                  - causeCode: cause.124-889198727RR0001
                    amountCents: 1050
                comments:
                  - cause: cause.124-119219814RR0001
                    commenter: Rob
                    comment: Goodness matters
                matchOverrides: 1,2,3,4
                tags:
                  - context2:tag_y
                  - report:payroll-donate
                  - spark-payroll-period:p2
    Donor:
        type: object
        required:
          - fullName
          - email
        properties:
          fullName:
            type: string
            maxLength: 200
          email:
            type: string
            minLength: 3
            maxLength: 100
            format: email
          receipted:
            type: boolean
            description: Whether or not a receipt should be generated for the Donor provided.
            default: false
          address:
            $ref: '#/components/schemas/Address'
    DonationAttributes:
      type: object
      required:
        - destination
        - funds
      properties:
        destination:
          $ref: '#/components/schemas/Destination'
        donor:
          $ref: '#/components/schemas/Donor'
        funds:
          $ref: '#/components/schemas/Funds'
        metadata:
          $ref: '#/components/schemas/Metadata'
      example:
          destination:
            foundationId: 1XABCDE4UT
            recipientId: 124-119219814RR0001
          donor:
            fullName: Benevity User
            email: test@benevity.com
            receipted: true
            address:
              city: Calgary
              country: CA
              line1: 5555 Calgary St
              line2: Suite 101
              state: AB
              zip: T0A 1B2
          funds:
            amount: 1000
            currencyCode: CAD
            paymentType: DONATION_REPORT
            source: COMPANY
          metadata:
            vendor-id: abc-12382
            location: NW Calgary
            refill_date: 05/15/2023
    DonationsArrayResponseObject:
      allOf:
        - $ref: '#/components/schemas/JSONAPICursorPaginatedResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/DonationSubmitted'
    DonationSubmitted:
      title: Donation Submitted
      description: Donation submitted to the donation service
      allOf:
        - $ref: '#/components/schemas/DonationAttributes'
      properties:
        state:
          type: object
          properties:
            processingStatus:
              type: string
              description: | 
                The status of the donation.
                ACCEPTED - Donation accepted for processing in Benevity's platform, will become INITIATED or DECLINED.
                INITIATED - Processing in Benevity's platform.
                DECLINED - The donation could not be processed by the platform, see errors.
              enum: [ACCEPTED, INITIATED, DECLINED]
            statusLastUpdated:
              type: string
              format: ISO-8601 UTC
              description: The time when status is last updated.
            errors:
              description: List of errors.
              items:
                $ref: '#/components/schemas/ErrorObject'
      example:
        destination:
          foundationId: 1XABCDE4UT
          recipientId: 124-119219814RR0001
        donor:
          fullName: Benevity User
          email: test@benevity.com
          receipted: true
          address:
            city: Calgary
            country: CA
            line1: 5555 Calgary St
            line2: Suite 101
            state: AB
            zip: T0A 1B2
        funds:
          amount: 1000
          currencyCode: CAD
          paymentType: DONATION_REPORT
          source: COMPANY
          receiptId: 1YTWL8K9AC
        metadata:
          vendor-id: abc-12382
          location: NW Calgary
          refill_date: 05/15/2023
        state:
          processingStatus: ACCEPTED
          statusLastUpdated: '2021-01-16T00:26:15.202Z'
    DonationResponseObject:
      type: object
      properties:
        type:
          type: string
          description: The type of the resource.
          example: donations
        id:
          $ref: '#/components/schemas/JSONAPIId'
        attributes:
          $ref: '#/components/schemas/DonationSubmitted'
    DonationRequestObject:
      type: object
      properties:
        type:
          type: string
          description: The type of the resource.
          example: donations
        attributes:
          $ref: '#/components/schemas/DonationAttributes'
    EmailObject:
      type: object
      properties:
        type:
          type: string
          description: type of object
          example: emails
        attributes:
          type: object
          description: 'email address of receiver'
          example: { 'to': 'abc@xyz.com' }
    Error:
      description: |
        The Benevity Donation API uses standard HTTP response codes to indicate whether a request succeeded or failed. Codes in the 2xx
        range indicate a success, and all other codes indicate a failure. For 4xx and 5xx HTTP responses, a corresponding JSON error
        response is returned with more information indicating the cause of the failure(s). Each error code maps to a single error type,
        broken down as follows:

        * `authentication_error`
          * `invalid_credentials`
          * `unauthorized_ip`
        * `api_error`
          * `entity_not_found`
          * `method_not_allowed`
          * `not_acceptable`
          * `unsupported_media_type`
        * `invalid_request_error`
          * `validation`
        * `unknown_error`
          * `unknown_error`
      required:
        - errors
      type: object
      properties:
        errors:
          type: array
          description: list of errors
          items:
            $ref: '#/components/schemas/ErrorObject'
    ErrorDeprecated:
      description: |
        The Benevity Search Engine API uses standard HTTP response codes to indicate whether a request succeeded or failed. Codes in the 2xx
        range indicate a success, and all other codes indicate a failure. For 4xx and 5xx HTTP responses, a corresponding JSON error
        response is returned with more information indicating the cause of the failure(s). Each error code maps to a single error type,
        broken down as follows:

        * `api_error`
          * `entity_not_found`
        * `internal_server_error`
          * `internal_server_error`
        * `invalid_request_error`
          * `validation`
      required:
        - type
        - code
        - message
      properties:
        type:
          type: string
          enum:
            - api_error
            - internal_server_error
            - invalid_request_error
          description: The general type of error returned. Used to group similar errors together.
        code:
          type: string
          enum:
            - entity_not_found
            - internal_server_error
            - validation
          description: A short string indicating the error code reported. This code is able to be handled programmatically.
        message:
          type: string
          description: A human-readable message providing more details about the error.
        fields:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The field that failed validation. This name will match a parameter on the request object.
              message:
                type: string
                description: The reason why this field failed to validate.
          description: >-
            An optional array of errors indicating which fields on the request failed validation. This array is only ever present for
            `validation` errors.
    Destination:
        type: object
        required:
          - recipientId
        properties:
          foundationId:
            type: string
            description: The foundation id which the donation is routed through.
          recipientId:
            type: string
            description: The id of the Cause, Project or Portfolio to donate to.
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
          format: int32
        reason:
          type: string
      example:
        code: 100
        message: Service Unavailable
    ErrorObject:
      type: object
      properties:
        status:
          type: string
          description: The HTTP status code applicable to this error.
        title:
          type: string
          description: A short, human-readable summary of the problem.
        detail:
          type: string
          description: An explanation specific to this occurrence of the problem.
        code:
          type: string
          description: A unique code describing the error.
        source:
          $ref: '#/components/schemas/ErrorSource'
        links:
          $ref: '#/components/schemas/JSONAPILinkObject'
      example:
        status: 400
        title: Bad Request
        detail: Error in processing.
        code: 1000
    ErrorSource:
      type: object
      properties:
        pointer:
          type: string
          description: A JSON pointer to the associated entity in the request document.
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error.
    Facet:
      type: object
      properties:
        name:
          type: string
          description: A specific dimension of the search result set.
          example: state_facet
        buckets:
          type: array
          description: 'Values of the facet dimension that are present in the results, summarized by how many times they appear.'
          items:
            type: object
            properties:
              label:
                type: string
                description: The human-friendly display label of the facet aspect/dimension.
                example: California
              val:
                type: string
                description: 'A value of the facet aspect/dimension. Typically, this value should be used for any corresponding filters.'
                example: US-CA
              count:
                type: integer
                description: The number of results that have this facet aspect value.
                example: 5
    Fields:
        type: object
        properties:
          key:
            type: string
            example: bulk/123e4567-e89b-12d3-a456-426614174000/donations.gz
          bucket:
            type: string
            example: env-benevity-donation-service-private
          X-Amz-Algorithm:
            type: string
            example: AWS4-HMAC-SHA256
          X-Amz-Credential:
            type: string
            example: A..../us-east-1/s3/aws4_request
          X-Amz-Date:
            type: string
            example: 20210608T1818214Z
          X-Amz-Security-Token:
            type: string
            example: FQoGZXIvYXdzEMb//////////...i9kOQF
          Policy:
            type: string
            example: eyJleHBpcmF0a...UYifV19
          X-Amz-Signature:
            type: string
            example: 05ed426704d359c1c68b1....6caf2f3492e
    Funds:
      type: object
      required:
        - amount
        - currencyCode
        - paymentType
        - source
      properties:
        amount:
          type: number
          format: int64
          description: The amount in credits.
          minimum: 1
        currencyCode:
          type: string
          description: The currency code, must follow the ISO-4217 standard.
        paymentType:
          type: string
          description: The payment method used to process the donation.
          enum: [DONATION_REPORT]
        source:
          type: string
          description: The source of funds used to process the donation.
          enum: [COMPANY]
        receiptId:
          type: string
          description: The unique Id of receipt generated on making a guest donation, if "receipted" is marked true for the donor.
    GetBulkIntentResponse:
      type: object
      required:
        - data
      properties:
        data:
           $ref: '#/components/schemas/BulkIntentResponseAttributes'
    GetCauseDetailsResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/GetCauseDetailsResponseObject"
    GetCauseDetailsResponseObject:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          allOf:
            - $ref: "#/components/schemas/JSONAPIType"
            - example: causes
        id:
          allOf:
            - $ref: "#/components/schemas/JSONAPIId"
            - example: 840-99999999
        attributes:
          type: object
          description: The attributes of the target cause.
          $ref: "#/components/schemas/CauseAttributes"
    GetCauseCategoryListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetCauseCategoryListResponseObject'
      required:
        - data
    GetCauseCategoryListResponseObject:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          example: categories
          allOf:
            - $ref: '#/components/schemas/JSONAPIType'
            - example: causes
        id:
          allOf:
            - $ref: '#/components/schemas/JSONAPIId'
        attributes:
          $ref: '#/components/schemas/CategoryAttributes'
    GetGeographicalRegionResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetGeographicalRegionResponseObject'
      required:
        - data
    GetGeographicalRegionResponseObject:
      type: object
      required:
        - type
        - id
        - attributes
      properties:
        type:
          example: regions
          allOf:
            - $ref: '#/components/schemas/JSONAPIType'
            - example: causes
        id:
          allOf:
            - $ref: '#/components/schemas/JSONAPIId'
        attributes:
          $ref: '#/components/schemas/GeographicalRegionAttributes'
    GetDonationResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/DonationResponseObject'
    GiveOpCause:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: Name of the cause.
          example: Junior Achievement of Canada
        logo_url:
          type: string
          description: 'URL of the cause''s logo. Images can be png, gif, or jpeg, and are of dimension 150x150.'
          example: 'https://my-cdn.com/150x150/public/clogos/cause_logo_image.png'
        geo_coordinates:
          type: object
          properties:
            latitude:
              type: string
            longitude:
              type: string
          description: The Geo-Coordinates of the cause.
    GiveOpProject:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: Name of the project.
          example: Honeybees
        cause:
          $ref: '#/components/schemas/GiveOpCause'
        geo_coordinates:
          type: object
          properties:
            latitude:
              type: string
            longitude:
              type: string
          description: The Geo-Coordinates of the project.
    GivingOpportunity:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: The unique identifier for this giving opportunity.
        title:
          type: string
          description: The title of the giving opportunity.
          example: Support the Benevity Bee Hive
        description:
          type: string
          maxLength: 180
          nullable: true
          description: A quick summary or description of the giving opportunity.
          example: Show your status as an RFOBee!
        image_url:
          type: string
          nullable: true
          description: 'URL of the giving opportunity''s main image. Images can be png, gif, or jpeg, and have dimensions between 300x225 and 5000x5000.'
        creator_name:
          type: string
          description: The creator name of the giving opportunity.
        creator_type:
          type: string
          enum:
            - user
            - company
            - team
          description: The type indicates the category of the creator of the giving opportunity.
        product_area:
          type: string
          description: The product area of the creator of the giving opportunity.
        office_location:
          type: string
          description: The office location of the creator of the giving opportunity.
        tags:
          type: array
          items:
            type: string
            example: Campaign Week 2019
          description: Freeform labels that can be attached to a giving opportunity.
        snippets:
          type: object
          properties:
            title:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's title.
            cause:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's cause or project name.
            body:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's description or summary.
            tag:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's tags.
          description: >-
            Snippets are fragments of text that reveal the contextual relevance between the search terms and the search results. Matching
            search terms are surrounded by emphasis tags <em> </em>. The following categories of snippets are available: title, cause, body,
            tag.
        causes:
          type: array
          items:
            $ref: '#/components/schemas/GiveOpCause'
          description: Causes that this opportunity is in support of.
        projects:
          type: array
          items:
            $ref: '#/components/schemas/GiveOpProject'
          description: Projects that this opportunity is in support of.
    JSONAPIResourceIdentifierObject:
      title: JSON:API Resource Identifier Object
      description: |
        A JSON:API-compliant resource identifier object. An inheritable object schema that contains the basic framework of a Resource Identifier Object from the JSON:API spec.
        A “resource identifier object” is an object that identifies an individual resource.
        A “resource identifier object” MUST contain `type` and `id` members.
        A “resource identifier object” MAY also include a `meta` member, whose value is a meta object that contains non-standard meta-information. If necessary, the `meta` property should be added by the inheriting schema.
      type: object
      required:
        - type
        - id
      properties:
        type:
          $ref: '#/components/schemas/JSONAPIType'
        id:
          $ref: '#/components/schemas/JSONAPIId'
    JSONAPIType:
      title: JSON:API type Member
      description: |
        The `type` member is used to describe resource objects that share common attributes and relationships.
        Note: The type member is required in every resource object throughout requests and responses in JSON:API. 
        There are some cases, such as when POSTing to an endpoint representing heterogeneous data, when the type could not be inferred from the endpoint. 
        However, picking and choosing when it is required would be confusing; it would be hard to remember when it was required and when it was not. 
        Therefore, to improve consistency and minimize confusion, type is always required.
      type: string
    JSONAPIId:
      title: JSON:API id Member
      description: |
        Every resource object MUST contain an id member and a type member 
        (exception-the id member is not required when the resource object originates at the client and represents a new resource to be created on the server). 
        Within a given API, each resource object’s type and id pair MUST identify a single, unique resource.
      type: string
      example: 123e4567-e89b-12d3-a456-426614174000
    JSONAPIRelationshipObject:
      title: JSON:API Relationship Object
      description: |
        This schema can be used when defining `relationships` objects within a JSON:API resource object.
        The value of the relationships key MUST be an object (a “relationships object”). 
        Members of the relationships object (“relationships”) represent references from the resource object in which it’s defined to other resource objects.
        Relationships may be to-one or to-many.
      type: object
      oneOf:
        - type: object
          description: links object
          properties:
            links:
              $ref: '#/components/schemas/JSONAPILinksObject'
        - type: object
          description: |
            Resource linkage in a compound document allows a client to link together all of the included resource objects without having to GET any URLs via links.
            Resource linkage MUST be represented as one of the following:
            * null for empty to-one relationships.
            * an empty array ([]) for empty to-many relationships.
            * a single resource identifier object for non-empty to-one relationships.
            * an array of resource identifier objects for non-empty to-many relationships.
          properties:
            data:
              oneOf:
                - type: string
                  description: null indicates an empty to-one relationship
                  default: 'null'
                - type: array
                  description: an empty array indicates an empty to-many relationship; an array with objects indicates a non-empty to-many relationship
                  items:
                    $ref: '#/components/schemas/JSONAPIResourceIdentifierObject'
                - $ref: '#/components/schemas/JSONAPIResourceIdentifierObject'
        - type: object
          description: a meta object that contains non-standard meta-information about the relationship
          properties:
            meta:
              type: object
    JSONAPICursorPaginatedResponse:
      title: JSON:API Resource Collection
      description: |
        The base document returned when fetching a collection of resources.
        Must include "data" as an array of resource identifier objects.
        May include "meta" and "links".
      type: object
      required:
        - data
      properties:
        meta:
          $ref: '#/components/schemas/JSONAPIMetaCursorObject'
        links:
          type: object
          description: links object
          allOf:
            - $ref: '#/components/schemas/JSONAPICursorLinksObject'
        data:
          type: array
          items:
            $ref: '#/components/schemas/JSONAPIResourceIdentifierObject'
    JSONAPIMetaCursorObject:
      title: JSON:API Cursor Pagination Metadata
      description: Cursor metadata
      type: object
      properties:
        count:
          type: number
          example: 1000
        page:
          type: object
          properties:
            rangeTruncated:
              type: boolean
              description: true if the collection is truncated
    JSONAPICursorLinksObject:
      title: JSON:API Cursor Pagination Links Object
      description: Cursor specific pagination links, may include prev, next. Start and end may not be known.
      properties:
        prev:
          $ref: '#/components/schemas/JSONAPILink'
        next:
          $ref: '#/components/schemas/JSONAPILink'
    JSONAPILinksObject:
      allOf:
        - $ref: '#/components/schemas/JSONAPICursorLinksObject'
      title: JSON:API Links Object
      description: May contain `self`, `related`, or pagination links (first, last, prev, next).
      properties:
        self:
          $ref: '#/components/schemas/JSONAPILink'
        related:
          $ref: '#/components/schemas/JSONAPILink'
        first:
          $ref: '#/components/schemas/JSONAPILink'
        last:
          $ref: '#/components/schemas/JSONAPILink'
    JSONAPILink:
      title: JSON:API Link
      description: A JSON:API link can be either a URL string or a structured link object.
      oneOf:
        - $ref: '#/components/schemas/URL'
        - $ref: '#/components/schemas/JSONAPILinkObject'
    JSONAPILinkObject:
      title: JSON:API Link Object
      description: a structured representation of a URL
      type: object
      properties:
        href:
          type: string
          example: 'https://example.com/'
        meta:
          type: object
          example:
            count: '10'
    Metadata:
      type: object
      description: A map of metadata tags for the donation request. Metadata key should only contain alphanumeric characters with spaces/underscores/dashes, and can be from 1 to 64 characters long (^[A-Za-z0-9-_\\s]{1,64}$). Metadata value allows any characters in the [Basic Multilingual Plane](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane) except [surrogates](https://unicode.org/faq/utf_bom.html#utf16-2), and can be from 1 to 190 characters long (^[\u0000-\uD7FF\uE000-\uFFFF]{1,190}$).
      maxProperties: 100
      additionalProperties:
        type: string
        pattern: '^[\u0000-\uD7FF\uE000-\uFFFF]{1,190}$'
        maxLength: 190
      example:
        vendor-id: abc-12382
        location: NW Calgary
        refill_date: 05/15/2023
    Pagination:
      description: Paging information to help navigate the local neighbourhood of search results.
      type: object
      properties:
        current:
          type: integer
          format: int32
          description: The current page of the search results.
        next:
          type: string
          description: URL of the next page of search results.
        previous:
          type: string
          description: URL of the previous page of search results.
        other_pages:
          type: array
          items:
            type: string
          description: URLs of pages surrounding the current page of search results. With a maximum of 9 surrounding pages.
    PaymentConfig:
      type: object
      properties:
        token:
          type: string
          description:
            PaymentToken from the Merchant. For instance, pfToken from
            Bluesnap
        processor:
          type: string
          description: The MerchantProcessor
          default: BLUESNAP
        merchantAccountId:
          type: string
          description: Benevity ID of the merchant account to use
        mid:
          type: string
          description: Merchant Id from the Processor
      example:
        token: abcde12345
        processor: BLUESNAP
        merchantAccountId: 3A27DYHR3J
        mid: '1234'
    PaymentFieldsToken:
      type: object
      description: Payment Fields Token.
      required:
        - adapter
        - companyCode
      properties:
        adapter:
          type: string
          description: The adapter through which the request will be routed.
        companyCode:
          type: string
          description: The id of the company associated with the Transaction the Payment Fields Token is associated with.
        userAccessId:
          type: string
          description: Optional Benevity Id of the User for which the Transaction will be associated.
    PaymentFieldsTokenRequest:
      type: object
      description: Payment Fields Token request.
      required:
        - causeId
        - causeType
        - currencyCode
      allOf:
        - '$ref': '#/components/schemas/PaymentFieldsToken'
        - properties:
            causeId:
              type: string
              description: The id of the cause, project or portfolio.
            causeType:
              type: string
              description: The type of the object referred to by the causeId. CAUSE, PROJECT or PORTFOLIO.
              enum: [CAUSE, PROJECT, PORTFOLIO]
            currencyCode:
              type: string
              description: The currency code. Must be a valid ISO-4217 currency code.
    PaymentFieldsTokenResponse:
      type: object
      description: Payment Fields Token response.
      allOf:
        - '$ref': '#/components/schemas/PaymentFieldsToken'
        - properties:
            merchantAccountId:
              type: string
              description: The id of the Merchant Account associated with the Payment Fields Token.
            paymentType:
              type: string
              description: The Payment method associated with the Payment Fields Token.
            processor:
              type: string
              description: The Payment Processor to which the token is associated.
            token:
              type: string
              description: The Hosted Payment Fields Token from the Payment processor.
            userId:
              type: string
              description: The id of the Payments User created as part of the request. In UUID format.
      example:
        adapter: 'Adapter.Wpg'
        companyCode: '1NEMNC6BDZ'
        merchantAccountId: '1N0732D4BP'
        userAccessId: 'user-can'
        paymentType: 'CREDITCARD'
        processor: 'BLUESNAP'
        token: 'ac650ebc46837676c48e2d2b979a0199ee1f2efc0cea62295ba3c63f6566e007_'
        userId: '6952a640-8fb7-4f77-b35c-4c0ed05dae2a'
        requiredData: ['billingFullName', 'billingEmail']
    PaymentMethod:
      type: object
      required:
        - enabled
        - merchantAccountId
        - merchantAccountName
        - processor
      properties:
        enabled:
          type: boolean
          description: Indicates if this PaymentMethod is enabled or not
          default: false
        merchantAccountId:
          type: string
          description: The MerchantAccountId of the MerchantAccount for which this PaymentMethod is valid
          default: 'AOGFMerchAcctId'
        merchantAccountName:
          type: string
          description: Human-understandable merchant account name
        mid:
          type: string
          description: Merchant Id from the MerchantProcessor
          default: '1234'
        processor:
          type: string
          description: The MerchantProcessor for which this PaymentMethod is valid
          default: 'bluesnap'
    PaymentMethods:
      type: object
      allOf:
        - properties:
            creditCard:
              $ref: '#/components/schemas/CreditCardPaymentMethod'
            applePay:
              $ref: '#/components/schemas/ApplePayPaymentMethod'
            visaCheckout:
              $ref: '#/components/schemas/VisaCheckoutPaymentMethod'
          example:
            creditCard:
              processor: 'bluesnap'
              enabled: 'true'
              merchantAccountId: 'AOGFMerchAcctId'
              merchantAccountName: 'AOGFBluesnap'
              hasTokenizedElsewhere: 'false'
              savedCards:
                - name: 'Scene Visa Card'
                  creditCardId: 'card54321'
                  last4digits: '1234'
                  expiryMonth: '01'
                  expiryYear: '2017'
                  cardAssociation: 'VISA'
                  cardType: 'CREDIT'
                - name: 'West Jet Card'
                  creditCardId: 'card54322'
                  last4digits: '1235'
                  expiryMonth: '01'
                  expiryYear: '2019'
                  cardAssociation: 'VISA'
                  cardType: 'CREDIT'
            applePay:
              processor: 'bluesnap'
              enabled: 'true'
              merchantAccount: 'AOGFMerchAcctId'
              mid: '1234'
            visaCheckout:
              processor: 'bluesnap'
              enabled: 'true'
              merchantAccount: 'AOGFMerchAcctId'
    PingResponse:
      type: object
      required:
          - data
      properties:
        data:
          $ref: '#/components/schemas/PingResponseObject'
    PingResponseObject:
      type: object
      properties:
        type:
          type: string
          description: The type of the resource.
          example: health
        id:
          type: string
          description: Unique identifier for the Donation resource.
          example: 0
        attributes:
          type: object
          properties:
            message:
              type: string
              description: A message indicating the response.
          example:
            message: Pong
    PurchaseAllocation:
      required:
        - amountCents
        - causeCode
      type: object
      properties:
        causeCode:
          type: string
          description: Cause code
          default: cause.124-119219814RR0001
        amountCents:
          minimum: 1
          type: number
          description: Amount of money to allocate to this cause/portfolio/project
    PurchaseComment:
      required:
        - cause
        - comment
        - commenter
      type: object
      properties:
        cause:
          maxLength: 100
          type: string
          description:
            the portfolio/cause/project id which associated with the comment
            such as "cause.124-119219814RR0001"
        commenter:
          maxLength: 200
          type: string
          description:
            The name of the person or organization who made the comment
            such as Rob
        comment:
          maxLength: 5000
          type: string
          description: the words for the comment such as Goodness Matters
          format: int64
    PurchaseItem:
      required:
        - action
        - allocations
        - itemTotalAmountCents
        - name
        - quantity
      type: object
      properties:
        name:
          maxLength: 1024
          type: string
          description: Named identifier
        action:
          type: string
          description: The type of purchase item
        quantity:
          minimum: 1
          type: integer
          description: Quantity of this item.
          format: int32
        itemTotalAmountCents:
          minimum: 1
          type: number
          description: Total Amount for this item in cents
          format: int64
        matchCap:
          type: number
          description: Maximum amount of match customized by donator
          format: int64
        matchOverrides:
          type: array
          description: Match overrides
          items:
            type: string
        receiptNote:
          maxLength: 100
          type: string
          description: Optional note for the receipt
        customReceiptBanner:
          maxLength: 100
          type: string
          description: Banner for the receipt
        sharing:
          type: boolean
          description: Indicates if pii can be shared
          default: false
        sendReceipt:
          type: boolean
          description: Indicates if a receipt should be sent to the donor or not
          default: true
        comments:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseComment'
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseAllocation'
        tags:
          type: array
          description: Custom Tags that can be sent to the backend
          items:
            type: string
    UserTransactionRequest:
      type: object
      allOf:
        - '$ref': '#/components/schemas/CreditCardTransactionRequest'
        - properties:
            userId:
              type: string
              description: The id of the Payments User for which to process the Transaction. In UUID format.
            companyCode:
              type: string
              description: The id of the company associated with the Transaction.
      example:
        total: 1050
        currencyCode: 'USD'
        creditCardId: 'card54321'
        merchantAccountId: '38486450'
        companyCode: '1NEMNC6BDZ'
        userId: '6952a640-8fb7-4f77-b35c-4c0ed05dae2a'
        paymentConfig:
          token: 'abcde12345'
          merchantAccountId: '3A27DYHR3J'
          processor: 'BLUESNAP'
        cardHolder:
          fullName: Test User
          email: testuser@email.com
          country: ca
          address: Test
          address2: Apt 101
          provinceState: bc
          postalZip: 90210
          city: Test
        adapter: 'Adapter.Wpg'
        transactionReason: 'user_donation'
        sourceMetadataValue: 'spark.benevity.org'
        description: '$10.50 Donation to Test'
        softDescriptor: 'Benevity'
        referenceNumber: 'hb7ue7s0dn196dfkebm0ulekr2-59f8fe7257fc37.57584560'
        locale: 'en_us'
        payerBusinessName: 'google'
        purchaseItems:
          - name: 'itemname'
            action: 'COMPANYDONATEFORUSER'
            quantity: 1
            itemTotalAmountCents: 1050
            matchCap: 50
            receiptNote: 'Note'
            customReceiptBanner: 'banner.png'
            sharing: false
            sendReceipt: true
            allocations:
              - causeCode: 'cause.124-889198727RR0001'
                amountCents: 1050
            comments:
              - cause: 'cause.124-119219814RR0001'
                commenter: 'Test'
                comment: 'Goodness matters'
            matchOverrides: '1,2,3,4'
            tags:
              [
                  'context2:tag_y',
                  'report:payroll-donate',
                  'spark-payroll-period:p2',
              ]
    ReceiptEmailRequest:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/EmailObject'
    Refund:
      type: object
      properties:
        refundDate:
          type: string
          format: date-time
        amount:
          $ref: '#/components/schemas/Amount'
    SearchInformation:
      type: object
      properties:
        showing_results_for:
          type: string
          description: >-
            The q string that was used for generating current search results. If this value is equal to spell_check_suggestion, then there
            were no results for the original search term and a spell check suggested query was used instead.
        spell_check_suggestion:
          type: string
          description: 'The spell check suggested query string. If null, then there are no spell check suggestions for better search results.'
    Shift:
      type: object
      properties:
        shift_name:
          type: string
          maxLength: 255
          description: The name of the shift.
          example: General
        allow_guests:
          type: string
          description: Indicates whether the shift allows guest participation.
          enum:
            - true
            - false
          default: 'false'
        accept_waitlist:
          type: string
          description: Indicates whether the shift accepts waiting list.
          enum:
            - true
            - false
          default: 'true'
        signups_max:
          type: integer
          format: int32
          maxLength: 11
          description: The maximum number of participants allowed for the shift. Will be `null` if no shift signup limit is set.
          example: 100
        signups_remaining:
          type: integer
          format: int32
          maxLength: 11
          description: Indicates the number of spots available for the shift. Will be `null` if no shift signup limit is set.
          example: 100
        start_timestamp:
          type: string
          format: date-time
          description: The start date time of the shift in ISO 8601 format.
          example: '2019-02-01T21:00:00+00:00'
        end_timestamp:
          type: string
          format: date-time
          description: The end date time of the shift in ISO 8601 format.
          example: '2019-02-01T21:00:00+00:00'
    Status:
      type: string
      enum:
        - PENDING
        - UPLOADED
        - VALIDATED
        - PROCESSING
        - PROCESSED
        - ERROR
      description: >
        * PENDING - bulk intent has been created, waiting for you to upload your file
        * UPLOADED - your upload has been detected and will validate
        * VALIDATED - your upload has been validated and is ready for processing
        * PROCESSING - your file is currently being processed
        * PROCESSED - your donations have been accepted by Benevity for further processing
        * ERROR - validation or processing error has occurred
    Transaction:
      type: object
      properties:
        creditCardId:
          maxLength: 100
          type: string
          description:
            The <b>creditCardId</b> of the CreditCard used for this Transaction.
            The card must have already been tokenized on the merchant account
        amount:
          $ref: '#/components/schemas/Amount'
        referenceNumber:
          maxLength: 200
          type: string
          description:
            ReferenceNumber is a unique id to identify this transaction,
            can be passed in to the request and which will be returned in the response
        description:
          maxLength: 100
          type: string
          description: A description of the Transaction
        softDescriptor:
          maxLength: 20
          type: string
          description:
            A description to send to the MerchantProcessor that will display
            on the CreditCard statement
        countryCode:
          maxLength: 4
          type: string
          description: Country code
        locale:
          maxLength: 10
          type: string
          description: Locale
          default: en-us
        payerBusinessName:
          maxLength: 200
          type: string
          description: Payer Business Name. Optional
        transactionReason:
          maxLength: 255
          type: string
          description: The intention for this Transaction. Defaults to 'user_donation'
        purchaseItems:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseItem'
        giftAid:
          type: boolean
          description: Indicates if this donation is going to use Gift Aid or not
          default: false
    TransactionResponse:
      allOf:
        - $ref: '#/components/schemas/Transaction'
        - type: object
          properties:
            transactionId:
              type: string
              description: The <b>transactionId</b>
            created:
              type: number
              description: Timestamp for when the Transaction was created
              format: int64
            received:
              type: number
              description: Timestamp for when the Transaction was received
              format: int64
            processed:
              type: number
              description:
                Timestamp for when the Transaction was processed by the Merchant
                Processor
              format: int64
            backend:
              type: number
              description: Timestamp for when the Transaction was processed by the Backend
              format: int64
            refunded:
              type: number
              description:
                Timestamp for when the Transaction was refunded by the Merchant
                Processor
              format: int64
            recurring:
              type: boolean
              description: true if this is a subscription
            refunds:
              type: array
              items:
                $ref: '#/components/schemas/Refund'
            backendTransactionId:
              type: string
              description:
                The <b>backendTransactionId</b> of the Transaction in the
                Benevity backend
          example:
            creditCardId: card54321
            transactionId: '38486450'
            merchantAccountId: '38486450'
            amount:
              totalAmountCents: 5500
              currencyCode: USD
            description: Donation to VOKRA
            softDescriptor: Benevity
            countryCode: CAD
            referenceNumber: hb7ue7s0dn196dfkebm0ulekr2-59f8fe7257fc37.57584560
            locale: en_us
            payerBusinessName: google
            transactionReason: user_donation
            created: 1510358339482
            received: 1510358339482
            processed: 1510358339482
            backend: 1510358339482
            refunded: 1510358339482
            backendTransactionId: 7D3UBDPYHZ
            purchaseItems:
              - name: itemname
                action: USERPURCHASECREDITSANDDONATE
                quantity: 1
                matchCap: 100
                receiptNote: Note
                customReceiptBanner: banner.png
                sharing: false
                itemTotalAmountCents: 5500
                sendReceipt: true
                allocations:
                  - causeCode: cause.124-119219814RR0001
                    amountCents: 5500
                comments:
                  - cause: cause.124-119219814RR0001
                    commenter: Brent
                    comment: We do care
                matchOverrides: 1,2,3,4
                tags:
                  - context2:tag_y
                  - report:payroll-donate
                  - spark-payroll-period:p2
    URL:
      type: string
      format: url
      example: 'https://api.benevity.org/'
    VisaCheckoutPaymentMethod:
      type: object
      allOf:
        - '$ref': '#/components/schemas/PaymentMethod'
    Volop:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: The volunteer opportunity ID.
          example: 123
        prop_currency_id:
          type: string
          maxLength: 11
          description: The identifier of the opportunity's proprietary currency type.
          example: 4JRDJZ5R51
        status:
          type: string
          description: Current approval status of the opportunity.
          enum:
            - queued
            - approved
            - denied
        featured:
          type: string
          description: Whether or not this is a featured opportunity.
          enum:
            - false
            - true
        start_timestamp:
          type: string
          format: date-time
          description: 'The date and time that the event starts, as an ISO 8601 timestamp.'
          example: 2019-02-04T06:00:00.000Z
        end_timestamp:
          type: string
          format: date-time
          description: 'The date and time that the event ends, as an ISO 8601 timestamp.'
          example: 2019-02-06T08:00:00.000Z
        time_zone:
          type: string
          description: 'The time zone of the event, expressed as an IANA tzdb identifier.'
          example: America/Edmonton
          externalDocs:
            description: IANA Time Zone Database
            url: 'https://www.iana.org/time-zones'
        title:
          type: string
          maxLength: 255
          description: The title of the volunteering opportunity.
          example: Junior Achievement - Volunteer Day
        description:
          type: string
          maxLength: 180
          description: A quick summary or description of the volunteering opportunity.
          example: SPARKing entrepreneurship in young students
        location_notes:
          type: string
          description: Additional information about the location. May be present even if the opportunity doesn't have an address.
          example: >-
            We will pair up for each of the schools/classrooms that we attend. We will offer schools in Oakville, Whitby, Etobicoke and
            Burlington. Schools will be confirmed weeks in advance and will be based on everyone's personal location preference.
        cause_id:
          type: string
          description: ID of the cause that this opportunity is in support of.
          example: 124-1234567890
        cause_name:
          type: string
          description: Name of the cause that this opportunity is in support of.
          example: Junior Achievement of Canada
        project_name:
          type: string
          nullable: true
          maxLength: 255
          description: Name of the project that this opportunity is in support of.
          example: Honeybees
        image_url:
          type: string
          description: >-
            URL of the volunteer opportunity's main image. Images can be png, gif, or jpeg, and have dimensions between 300x225 and
            5000x5000.
          example: 'https://my-cdn.com/image.png'
        hero_image_url:
          type: string
          description: >-
            URL of the volunteer opportunity's hero/banner image. Hero images can be png, gif, or jpeg, and have dimensions between 1080x250
            and 5000x5000.
          example: 'https://my-cdn.com/hero_image.png'
        cause_logo_url:
          type: string
          description: 'URL of the volunteer opportunity''s cause logo. Images can be png, gif, or jpeg, and are of dimension 150x150.'
          example: 'https://my-cdn.com/150x150/public/clogos/cause_logo_image.png'
        score:
          type: number
          format: float
          description: A value representing the rank of relevance. The higher the score the more relevant it is.
        address:
          $ref: '#/components/schemas/Address'
        characteristics:
          type: array
          items:
            type: string
            example: Team Event
          description: Characteristics of the opportunity that users might wish to filter their results by.
        interests:
          type: array
          items:
            type: string
            example: Education
          description: Interests related to the opportunity that may appeal to potential volunteers.
        skills:
          type: array
          items:
            type: string
            example: Mentoring
          description: Desired skills that volunteers participating in the opportunity should have.
        geo_coordinates:
          type: object
          properties:
            latitude:
              type: string
            longitude:
              type: string
          description: The Geo-Coordinates of the volunteering opportunity.
        shifts:
          type: array
          items:
            $ref: '#/components/schemas/Shift'
        snippets:
          type: object
          properties:
            title:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's title.
            cause:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's cause or project name.
            body:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's description or summary.
            tag:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's tags.
            location:
              type: array
              items:
                type: string
              description: A highlighted fragment of text that matches the user's search terms in the opportunity's location details.
          description: >-
            Snippets are fragments of text that reveal the contextual relevance between the search terms and the search results. Matching
            search terms are surrounded by emphasis tags <em> </em>. The following categories of snippets are available: title, cause, body,
            tag and location.
  securitySchemes:
    Oauth2:
      type: oauth2
      description: Oauth 2.0 application authentication
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            benevity/api: Access to Benevity API
    bearerAuth:
      description: |
        Authorization using a JWT. The JWT should have the following properties:
        * The body of the JWT must contain the following keys:
          * `iss`: The issuer of the JWT. This must match your API client key.
          * `uid`: The user id for the request. This value must be a string and represents the user of your system upon whose behalf this request is made. If your system doesn't require individual users, use a consistent value.
          * `exp`: The expiry of the JWT. This value must be in seconds from the Unix epoch, and must be no longer than 35 minutes from the time of the request.
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    BadRequestDeprecated:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDeprecated'
          example:
            type: invalid_request_error
            code: validation
            message: One or more validation errors were present in the request.
            fields:
              - name: highlights
                message: This field must be true or false.
              - name: page
                message: This field must be a positive integer.
              - name: page_size
                message: This field must be a positive integer less than or equal to 100.
              - name: start_timestamp
                message: This field must be in ISO 8601 format.
              - name: end_timestamp
                message: This field must be in ISO 8601 format.
              - name: start_timestamp
                message: Start time must be before end time.
              - name: location
                message: 'Location must be numeric and in this format: latitude,longitude.'
              - name: location
                message: 'Location must be within limits: latitude -90 to 90, longitude -180 to 180.'
    NotFoundDeprecated:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDeprecated'
          example:
            type: api_error
            code: entity_not_found
            message: The resource could not be found.
    InternalServerErrorDeprecated:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDeprecated'
          example:
            type: internal_server_error
            code: internal_server_error
            message: An internal server error has occurred.
    ServiceUnavailable:
      description: Service Unavailable.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: 503
                title: Service Unavailable
                detail: Benevity donation service is not reachable or available
    UnauthorizedDeprecated:
      description: Unauthorized
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/ErrorDeprecated'
    BadRequest:
      description: Bad Request
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Malformed:
              value:
                errors:
                  - status: 400
                    title: Bad Request
                    source: {}
                    detail: Malformed request syntax
            Query Param:
              value:
                errors:
                  - status: 400
                    title: Bad Request
                    source: {"parameter":"page[size]"}
                    detail: Invalid parameter
            Payload:
              value:
                errors:
                  - status: 400
                    title: Bad Request
                    source: {"pointer":"id"}
                    detail: Invalid request payload
    InternalServerError:
      description: Internal Server Error
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: 500
                title: Internal Server Error
                source: {}
                detail: Something went wrong, please contact Benevity Support
    NotFound:
      description: Not Found
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: 404
                title: Not Found
                source: { 'parameter': 'receiptId' }
                detail: Receipt not found / Invalid Receipt Id
    Unauthorized:
      description: Unauthorized
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: 401
                title: Unauthorized
                source: { 'pointer': 'company_code' }
                detail: Access denied
    Forbidden:
      description: Forbidden.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
              - status: 403
                title: Forbidden
                source: { "pointer": "company_code" }
                detail: Access denied
  parameters:
    searchLocation:
      name: search_location
      in: query
      description: >-
        The origin point of the search, expressed as `latitude,longitude`. Generally, results physically closer to this point will be ranked
        higher in the results. Latitude must be between -90 and 90, and longitude must be between -180 and 180.
      schema:
        type: string
        example: '51.051651,-114.050880'
    country:
      name: country
      in: query
      description: >-
        The search result is filtered based on the country associated with the project or cause. The filter values can be either the ISO
        3166 standard numeric codes or the extended version of alphanumeric codes which can be found in the response facets. This parameter
        can be used multiple times for different values. The values will be OR'd together.
      schema:
        type: array
        items:
          type: string
        example:
          - US
          - 124
    state:
      name: state
      in: query
      description: >-
        The search result is filtered based on the state, province or region associated with the project or cause. The filter values are the
        extended version of ISO 3166-2 standard and can be found in the response facets. This parameter can be used multiple times for
        different values. The values will be OR'd together.
      schema:
        type: array
        items:
          type: string
        example:
          - US-NY
          - CA-AB
    category:
      name: category
      in: query
      description: >-
        The search result is filtered based on the categories and subcategories the project or cause is associated with. The filter values
        are the NTEE standard and can be found in the response facets. Regions outside the USA with their own category system will be mapped
        to NTEE. This parameter can be used multiple times for different values. The values will be OR'd together. When a category and one
        or more of its subcategories are supplied, the parent category will be ignored. For example, `N`, `N61` are both supplied, the
        search result will be filtered by `N61` only.
      schema:
        type: array
        items:
          type: string
        example:
          - A03
    visibility:
      name: visibility
      in: query
      description: |
        Filter results based on what actions may be taken. For example a visibility of `donate` will only return causes that may be
        donated to. Loosening the filter to `program` will additionally return causes that may be linked to as part of your company's
        program but cannot receive donation. Each visibility level is a subset of the next, ending at `inactive` which allows the full
        set of results.

        * `donate` - Only view results that may be donated to.
        * `program` - Also view results that are part of your company's program.
        * `nominate` - Also view results that may be part of your company's program but are in an undetermined state and need to be
        nominated. A nomination involves prompting the cause to update their information.
        * `ineligible` - Also view results that are excluded from your company's program.
        * `inactive` - Also view any inactive results. This visibility allows you to view every record in our system.
        ---
      schema:
        type: string
        enum:
          - donate
          - program
          - nominate
          - ineligible
          - inactive
        default: donate
        example: nominate
    rulesetTag:
      name: ruleset_tag
      in: query
      description: >-
        Your company's program is determined by filter rules that may have tags associated to them. This parameter allows you to specify
        through tags what filter rules should be considered when determining a result's visibility level.
      schema:
        type: array
        items:
          type: string
        example:
          - 'user-country:canada'
    foundation:
      name: foundation
      in: query
      description: >-
        Your company can be registered with one or more foundations. This parameter allows you to specify what foundations should be
        considered when determining a result's visibility level.
      schema:
        type: array
        items:
          type: string
        example:
          - 8DUNG7YM9D
    sort:
      name: sort
      in: query
      description: |
        Sort results based on selected option. If ommitted, the `default` option will be selected.
        An invalid option will result in a bad request.
        A `distance` sort requires a valid `search_location` parameter.
        * `default` - sort results using a combination of relevancy factors: text, donations and distance if `search_location`
           is specified.
        * `distance` - sort results by distance to the `search_location`.
        * `trending` - sort results by trending.
        * `donor` - sort results by unique donor count.
        ---
      schema:
        type: string
        enum:
          - default
          - distance
          - trending
          - donor
        default: default
        example: trending
    autocorrect:
      name: autocorrect
      in: query
      description: >-
        If set to true, search results will be returned for the spell check suggestion when there are no results for the original search
        term. The default is false (results for the spell check suggestion will not be returned).
      schema:
        type: boolean
        default: false
    includeChildren:
      name: include_children
      in: query
      description: 'If set to false, search results will be returned for parent causes only.'
      schema:
        type: boolean
        default: true
