openapi: 3.2.0
info:
  title: Chariot Verification Requests API
  version: v1
  description: The Chariot REST API. Please see https://docs.givechariot.com/api for more details.
  contact:
    name: Chariot Development Team
    url: https://givechariot.com/contact
    email: developers@givechariot.com
  termsOfService: https://givechariot.com/legal-nonprofit
servers:
- url: https://sandboxapi.givechariot.com
  description: Sandbox
- url: https://api.givechariot.com
  description: Production
tags:
- name: Verification Requests
paths:
  /v1/verification_requests:
    post:
      summary: Create a verification request
      description: 'Request verification of an unlisted organization. If the organization cannot be found through Chariot''s search,

        you can submit a verification request so that Chariot''s compliance team can review and verify the organization.'
      operationId: createVerificationRequest
      tags:
      - Verification Requests
      security:
      - bearerAuth: []
      requestBody:
        $ref: '#/components/requestBodies/CreateVerificationRequestRequest'
      responses:
        '201':
          description: The verification request was created
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationRequest'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '412':
          $ref: '#/components/responses/PreconditionFailedError'
    get:
      summary: List verification requests
      description: Returns a paginated list of all verification requests for the authenticated grantmaker.
      operationId: listVerificationRequests
      tags:
      - Verification Requests
      security:
      - bearerAuth: []
      parameters:
      - name: ein
        in: query
        description: Filter by EIN. If provided, only returns verification requests matching this EIN.
        required: false
        schema:
          type: string
      - name: page_limit
        in: query
        description: Limit the size of the list that is returned. The default (and maximum) is 100 objects.
        required: false
        schema:
          type: integer
          format: int32
      - name: page_token
        in: query
        description: A token to use to retrieve the next page of results.
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/ListVerificationRequestsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/verification_requests/{id}:
    get:
      summary: Get a verification request
      description: Get a specific verification request by its unique identifier.
      operationId: getVerificationRequest
      tags:
      - Verification Requests
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier of the verification request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The verification request
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationRequest'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ProblemDetails:
      type: object
      description: RFC 7807 problem-details error (media type application/problem+json). The `status` field is an integer HTTP status code.
      required:
      - type
      - title
      - status
      - detail
      properties:
        type:
          type: string
          description: A URI reference identifying the problem type.
          example: about:blank
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          example: API Error
        status:
          type: integer
          description: The HTTP status code for this error.
          example: 400
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence.
          example: The request is invalid or contains invalid parameters.
      example:
        type: about:blank
        title: API Error
        status: 400
        detail: The request is invalid or contains invalid parameters.
    VerificationRequest:
      type: object
      description: 'A verification request allows grantmakers to request that Chariot''s compliance team verify an unlisted organization,

        enabling disbursements to nonprofits not yet in Chariot''s database.'
      required:
      - id
      - ein
      - organization_name
      - organization_id
      - status
      properties:
        id:
          type: string
          description: Unique identifier for the verification request
          example: vr_01jpjen1s23s29kkmnjsb6fzga
          readOnly: true
        ein:
          type: string
          description: The EIN of the organization being verified
          example: '123456789'
        organization_name:
          type: string
          description: The name of the organization as provided by the grantmaker
          example: Local Community Foundation
        organization_id:
          type: string
          description: The ID of the Organization record for the nonprofit being verified.
          example: org_01jpjenf5q6cawy43yxfcrxhct
        status:
          $ref: '#/components/schemas/VerificationRequestStatus'
        website:
          type: string
          description: The organization's website URL
          example: https://localfoundation.org
        recommended_mailing_address:
          $ref: '#/components/schemas/VerificationRequestAddress'
        verified_at:
          type: string
          format: date-time
          description: When the organization was verified as tax-exempt and eligible for disbursements
          readOnly: true
        failed_at:
          type: string
          format: date-time
          description: When the verification request was rejected
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: When the verification request was created
          example: '2020-01-31T23:00:00Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: When the verification request was last updated
          example: '2020-01-31T23:00:00Z'
          readOnly: true
    VerificationRequestStatus:
      type: string
      description: "The status of the verification request.\nPossible values include:\n  - `needs_review`: The request has been submitted and is awaiting review by Chariot's compliance team\n  - `verified`: The organization has been verified as tax-exempt and eligible for disbursements\n  - `failed`: Chariot's compliance team determined the organization is not eligible"
      example: needs_review
      enum:
      - needs_review
      - verified
      - failed
    VerificationRequestAddress:
      type: object
      description: A mailing address for the organization being verified.
      required:
      - line1
      - city
      - state
      - zip_code
      properties:
        line1:
          type: string
          description: Street address line 1
          example: 123 Main St
        line2:
          type: string
          description: Street address line 2 (suite, unit, etc.)
          example: Suite 100
        city:
          type: string
          description: City
          example: San Francisco
        state:
          type: string
          description: Two-letter US state code (e.g. "CA", "NY")
          example: CA
        zip_code:
          type: string
          description: ZIP or postal code
          example: '94105'
  responses:
    ListVerificationRequestsResponse:
      description: The response for VerificationRequests.list
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: '#/components/schemas/VerificationRequest'
              next_page_token:
                type: string
                description: "A cursor token to use to retrieve the next page of results by making another API call\n to the same endpoint with the same parameters (only changing the page_token). If\n specified, then more results exist on the server that were not returned, otherwise\n no more results exist on the server."
    PreconditionFailedError:
      description: Precondition Failed
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            PreconditionFailed:
              value:
                type: about:blank
                title: API Error
                status: 412
                detail: A precondition for the request was not met.
    ForbiddenError:
      description: Access denied
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            Forbidden:
              value:
                type: about:blank
                title: API Error
                status: 403
                detail: You do not have permission to access this resource.
    ConflictError:
      description: Resource Conflicts
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            Conflict:
              value:
                type: about:blank
                title: API Error
                status: 409
                detail: The request conflicts with the current state of the resource.
    BadRequestError:
      description: The request is invalid or contains invalid parameters
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            BadRequest:
              value:
                type: about:blank
                title: API Error
                status: 400
                detail: The request is invalid or contains invalid parameters.
    AuthenticationError:
      description: Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            Unauthorized:
              value:
                type: about:blank
                title: API Error
                status: 401
                detail: Authentication credentials were missing or invalid.
    NotFoundError:
      description: Resource Not Found
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            NotFound:
              value:
                type: about:blank
                title: API Error
                status: 404
                detail: The requested resource was not found.
    InternalServerError:
      description: Internal Server Error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            InternalServerError:
              value:
                type: about:blank
                title: API Error
                status: 500
                detail: The server encountered an error processing your request.
  headers:
    Location:
      description: The URI of the created object
      schema:
        type: string
    X-Request-Id:
      description: The unique identifier for the request
      schema:
        type: string
  requestBodies:
    CreateVerificationRequestRequest:
      description: The request to create a verification request for an unlisted organization.
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - ein
            - organization_name
            - recommended_mailing_address
            properties:
              ein:
                type: string
                description: The EIN of the organization to verify
                example: '123456789'
              organization_name:
                type: string
                description: The name of the organization as known to the grantmaker
                example: Local Community Foundation
              website:
                type: string
                description: The organization's website URL
                example: https://localfoundation.org
              recommended_mailing_address:
                $ref: '#/components/schemas/VerificationRequestAddress'
              contact_email:
                type: string
                description: Contact email for the nonprofit organization.
                example: contact@localfoundation.org
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer