Goodstack Agent Verifications API

openapi: 3.2.0
info:
  title: Goodstack Services Agent Verifications API
  version: v1
  x-logo:
    url: https://docs.goodstack.io/img/logo.png
    altText: Goodstack logo
  x-dark-logo:
    url: https://docs.goodstack.io/img/icons/Logo-white.svg
    altText: Goodstack logo
  contact:
    email: engineering-support@goodstack.io
    name: Api support
  description: '# Introduction


    Goodstack API allows you to build good into your product by facilitating charitable donations.'
servers:
- url: https://api.goodstack.io
  description: Production server
- url: https://sandbox-api.goodstack.io
  description: Sandbox server
tags:
- name: Agent Verifications
  description: 'Agent verification is a one-off check. It is used to confirm that:

    1. The person applying is who they say they are.

    2. They represent the nonprofit.


    They are not editable once created.'
paths:
  /v1/agent-verifications:
    get:
      security:
      - SecretApiKey: []
      summary: List Agent Verifications
      tags:
      - Agent Verifications
      parameters:
      - in: query
        name: status
        schema:
          type: string
          enum:
          - pending
          - pending_user_verification
          - pending_review
          - approved
          - rejected
      - in: query
        name: email
        schema:
          type: string
        description: filter on the Agent Verification list by email
        example: joe
      - in: query
        name: startDate
        schema:
          type: string
          format: date-time
        description: Start date to filter Agent Verifications.
        example: '2020-10-13T17:46:54.000Z'
      - in: query
        name: endDate
        schema:
          type: string
          format: date-time
        description: End date to filter Agent Verifications.
        example: '2020-10-13T17:46:54.000Z'
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successfully retrieved list of Agent Verifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentVerification'
                  object:
                    type: string
                    example: agent_verification
                  totalResults:
                    type: integer
                    example: 33
                  pageSize:
                    type: integer
                    example: 25
                  _links:
                    $ref: '#/components/schemas/CursorLinks'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                IncorrectParams:
                  $ref: '#/components/examples/IncorrectParams'
                CursorError:
                  $ref: '#/components/examples/Pagination.CursorError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
      operationId: getV1AgentVerifications
      x-operation-id-source: derived
    post:
      summary: Create an Agent Verification
      security:
      - SecretApiKey: []
      tags:
      - Agent Verifications
      parameters:
      - in: header
        name: Idempotency-Key
        schema:
          type: string
        required: false
        description: Idempotency key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  firstName:
                    type: string
                    description: First name of Agent
                    example: Max
                    maxLength: 255
                  lastName:
                    type: string
                    description: Last name of Agent
                    example: Plank
                    maxLength: 255
                  organisationId:
                    type: string
                    description: Id of the Organisation for which the Agent Verification is for
                    example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                  email:
                    type: string
                    description: Email Id of the agent
                    example: example@example.com
                    maxLength: 255
                  title:
                    type: string
                    example: Board Member
                    description: Job Title
                    maxLength: 255
                  organisationWebsite:
                    type:
                    - string
                    - 'null'
                    format: website
                    description: Organisation Website link
                    maxLength: 255
                  language:
                    type: string
                    description: Valid RFC 5646 language code
                required:
                - firstName
                - lastName
                - email
                - organisationId
              - type: object
                properties:
                  firstName:
                    type: string
                    description: First name of Agent
                    example: Max
                    maxLength: 255
                  lastName:
                    type: string
                    description: Last name of Agent
                    example: Plank
                    maxLength: 255
                  validationRequestId:
                    type: string
                    description: Validation Request Id if not part of organisation
                    example: validationrequest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                  email:
                    type: string
                    description: Email Id of the agent
                    example: example@example.com
                    maxLength: 255
                  title:
                    type: string
                    example: Board Member
                    description: Job Title
                    maxLength: 255
                  organisationWebsite:
                    type:
                    - string
                    - 'null'
                    format: website
                    description: Organisation Website link
                    maxLength: 255
                  language:
                    type: string
                    description: Valid RFC 5646 language code
                    example: en-GB
                required:
                - firstName
                - lastName
                - email
                - validationRequestId
      responses:
        '200':
          description: Successfully created a Agent Verification
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentVerification'
                  object:
                    type: string
                    example: agent_verification
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                OriginalCallInProgress:
                  $ref: '#/components/examples/Idempotency.OriginalCallInProgress'
                SameKeyDifferentData:
                  $ref: '#/components/examples/Idempotency.SameKeyDifferentData'
                KeyInUse:
                  $ref: '#/components/examples/Idempotency.KeyInUse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
      operationId: postV1AgentVerifications
      x-operation-id-source: derived
  /v1/agent-verifications/{id}:
    parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: Id of the Agent Verification.
    get:
      security:
      - SecretApiKey: []
      summary: Retrieve an Agent Verification
      tags:
      - Agent Verifications
      responses:
        '200':
          description: Successfully retrieved a Agent Verification
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentVerification'
                  object:
                    type: string
                    example: agent_verification
        '400':
          $ref: '#/components/responses/IncorrectParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1AgentVerificationsById
      x-operation-id-source: derived
    patch:
      security:
      - SecretApiKey: []
      summary: Edit an Agent Verification
      description: Update an Agent Verifications metadata.
      tags:
      - Agent Verifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  description: Metadata object that will be merged with current metadata object.
                  type: object
                  maxProperties: 20
                  additionalProperties:
                    description: Max key size is 40 characters. If key matches already existing key, it will override old value
                    type: string
                    maxLength: 250
      responses:
        '200':
          description: Successfully update Agent Verification metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentVerification'
                  object:
                    type: string
                    example: agent_verification
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InvalidMetadata:
                  $ref: '#/components/examples/AgentVerification.InvalidMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
      operationId: patchV1AgentVerificationsById
      x-operation-id-source: derived
components:
  examples:
    Idempotency.KeyInUse:
      summary: Idempotency - Key in use
      description: Idempotency Key is already in use
      value:
        error:
          code: idempotency/key_already_in_use
          title: Bad request
          message: Idempotency Key is already in use
    Idempotency.SameKeyDifferentData:
      summary: Idempotency - Data has changed from previous request
      description: Data has changed from previous request with this key
      value:
        error:
          code: idempotency/same_key_different_data
          title: Bad request
          message: Data has changed from previous request
    AgentVerification.InvalidMetadata:
      summary: 400 Bad request
      description: Metadata provided not correct format
      value:
        error:
          title: Bad request
          message: Metadata can only contain from 1 up to 20 keys, with key names up to 50 characters long and values up to 500 characters long
          code: agent_verification/invalid_metadata
    Idempotency.OriginalCallInProgress:
      summary: Idempotency - Original call in progress
      description: Original call with this idempotency key is still in progress, please wait and try again
      value:
        error:
          code: idempotency/original_call_in_progress
          title: Bad request
          message: Original call with this idempotency key is still in progress
    IncorrectParams:
      summary: 400 Incorrect Parameters
      description: Bad Request - Incorrect parameters
      value:
        error:
          code: bad_request
          title: Bad request
          message: One or more of the inputs were invalid
          reasons:
          - pageSize must be greater than or equal to 0
    Pagination.CursorError:
      summary: Error in cursor parameter
      description: We were unable to decode the cursor
      value:
        error:
          code: pagination/cursor_error
          title: Bad request
          message: Unable to find the next page
  parameters:
    pageSize:
      in: query
      name: pageSize
      required: false
      schema:
        type: integer
        minimum: 0
        default: 25
      description: How many items per page, for pagination.
    direction:
      in: query
      name: direction
      required: false
      schema:
        type: string
        enum:
        - ASC
        - DESC
      description: Which way to sort by the given 'sort' field.  Default DESC
    cursor:
      in: query
      name: cursor
      required: false
      schema:
        type: string
        example: eyJ2IjoxLCJkIjoibmV4dCIsImlkIjoiZG9uYXRpb25fMDAwMDAwQnc3U1BhMHBxOHBRMFFsckVaWGFaN3AifQ%3D%3D
      description: A cursor that points to where to start the page
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            title:
              type: string
            message:
              type: string
            reasons:
              type:
              - array
              - 'null'
              items:
                type: string
    AgentVerification:
      type: object
      properties:
        id:
          type: string
          example: agentverification_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        firstName:
          type: string
          example: Max
        lastName:
          type: string
          example: Plank
        organisationId:
          type:
          - string
          - 'null'
          example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
          description: Organisation Id
        organisation:
          type: object
          properties:
            id:
              type:
              - string
              - 'null'
              example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
              description: Organisation Id
            email:
              type:
              - string
              - 'null'
              example: org@example.com
              description: Organisation email
            name:
              example: Great Charity
              description: Organisation name
        email:
          type: string
          format: email
          example: example@example.com
        language:
          type: string
          example: en-GB
        validationRequestId:
          type:
          - string
          - 'null'
          example: validationrequest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        validationRequest:
          type: object
          properties:
            name:
              type:
              - string
              - 'null'
              example: Great Charity
        title:
          type:
          - string
          - 'null'
          example: Board Member
        rejectionReason:
          type:
          - string
          - 'null'
          deprecated: true
          description: Reason for rejecting agent verification
          enum:
          - Validation request failed
          - User verification expired
          - Identity check failed
          - No evidence agent’s email is associated with organisation
          - Agent/nonprofit will reapply
          - Agent used fake or test email
          - No online presence to complete check
          - Nonprofit association expired
          - Other
        rejectionReasonCode:
          type:
          - string
          - 'null'
          description: Reason code for rejecting agent verification
          enum:
          - validation_request_failed
          - user_verification_expired
          - user_failed_percent_review
          - reapply
          - fake_email_used
          - no_online_presence
          - nonprofit_association_expired
          - invalid_documentation
          - fake_documentation
          - mismatched_information
          - blank_corrupted_documentation
          - suspicious_application
          - other
        createdAt:
          type: string
          format: date-time
          example: '2020-10-13T17:46:54.000Z'
        status:
          type: string
          example: pending
          enum:
          - pending
          - pending_user_verification
          - pending_review
          - approved
          - rejected
        externalActionRequired:
          type: boolean
          example: true
    CursorLinks:
      type: object
      properties:
        current:
          type: string
          example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
        next:
          type: string
          example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
        prev:
          type: string
          example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
  responses:
    Unauthorized:
      description: Unauthorized
    ForbiddenScope:
      description: Forbidden (scope)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: forbidden
                  title:
                    type: string
                    example: Forbidden
                  message:
                    type: string
                    example: Access is denied due to missing scope permissions
    IncorrectParams:
      description: Error validating inputs
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: bad_request
                  title:
                    type: string
                    example: Bad request
                  message:
                    type: string
                    example: One or more of the inputs were invalid
                  reasons:
                    type: array
                    items:
                      type: string
                      example: pageSize must be greater than or equal to 0
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: not_found
                  title:
                    type: string
                    example: Resource not found
                  message:
                    type: string
                    example: This endpoint is unavailable or can not be found
  securitySchemes:
    PublishableApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key starting with 'pk_' that can be made public
    SecretApiKey:
      type: apiKey
      in: header
      description: API key starting with 'sk_' that must be kept secure
      name: Authorization
    DonationSessionToken:
      type: apiKey
      in: header
      name: donation-session-token
      description: Donation session token
x-tagGroups:
- name: NONPROFIT DATA
  tags:
  - Organisations
  - Countries
  - Registries
  - Categories
- name: NONPROFIT VALIDATIONS
  tags:
  - Validation Requests
  - Validation Request Documents
  - Validation Invites
  - Validation Submissions
  - Validation Submission Documents
  - Validation Submission Configuration
  - Monitoring Subscriptions
  - Eligibility Subscriptions
  - Activities
  - Agent Verifications
- name: MONETARY DONATIONS
  tags:
  - Donations
  - Donation Sessions
  - Users
  - Gift Aid
- name: WEBHOOK SUBSCRIPTIONS
  tags:
  - Webhook Subscriptions