Goodstack Validation Request Documents API

openapi: 3.2.0
info:
  title: Goodstack Services Validation Request Documents 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. We achieve this through the API''s listed and specified in this documentation. For all donations using the Goodstack API, Goodstack handles the vetting and validation of the good causes and onward the disbursement of the donation. The Goodstack API is organised around REST. All API responses, including errors, return JSON and use standard HTTP response codes. In all API requests you must specify the content-type HTTP header as application/json. All API requests must be made over HTTPS. # Authentication


    Authenticate your API requests by setting your live secret API key in the Authorization header. Two keys are provided to you, a publishable key prefixed with `pk_` and a secret key prefixed with `sk_`. Publishable API keys are meant solely to identify your goodstack account. These can safely be published in places like your JavaScript code, or in an Android or iPhone app and are meant for usage with our SDKs. Secret API keys should be kept confidential and only used in secure server environments. Anywhere that accepts a Publishable key will also accept a Secret key, but routes marked to accept a Secret key will not accept a Publishable key. # Formats


    ## IDs


    All ID fields are case-sensitive. For example, `abc123` and `ABC123` are treated as different IDs. ## Dates


    Dates are encoded as strings following the ISO 8601 standard `2025-08-01T12:00:00.000Z`. ## Pagination


    A maximum of 100 objects can be returned per request and the limit can be specified by using the pageSize query parameter. By default, the pageSize is set to 25. A `_links` object is included in paginated responses, which contains `next` and `prev` URLs to retrieve the next or previous pages of results. ## Monetary Values


    Throughout the API, monetary values are encoded as integers representing the amount in the smallest currency unit, for example 100 cents for a donation of $1.00. Currency is encoded as a string following the ISO 4217 standard (e.g. `USD`). ## Metadata


    Some objects have a metadata parameter that you can use to store key-value data. You can specify up to 20 keys, with key names up to 40 characters long and values up to 250 characters long. ## Errors


    The API returns standard HTTP response codes to indicate success or failure of API requests. Errors may include a custom error message. Error objects have these attributes, an `id`, a `message` corresponding to the HTTP response phrase of the error,

    an optional `invalid-params` attribute detailing issues with the request. An example error object returned from the API:

    ```json

    {

    error: {

    code: ''bad_request'',

    title: ''Bad request'',

    message: ''Something is wrong with your request, please check any parameters and try again'',

    reasons: [''amount is a required field'']

    }

    }

    ```


    A summary of the HTTP status codes returned from the api is listed in the table below. | Code | Title | Description |

    | ------------- |-------------| -----|

    | 200 | Success | Request successful |

    | 204 | No Content | Request successful with no content returned |

    | 400 | Bad Request | Request was invalid |

    | 401 | Unauthorised | Authorization header is invalid |

    | 403 | Forbidden | Insufficient permissions |

    | 404 | Not Found | Resource does not exist |

    | 429 | Too Many Requests | Rate Limited |

    | 500s | Internal Server Error | Something went wrong with the Goodstack API |


    # Enum Values


    Generally enum fields in our API are open-ended. New values may be added to an enum and this is not considered a breaking change. ## Integrating safely


    If your code handles enum values exhaustively — for example, a switch without a default case, or deserialisation into a strict typed enum — an unrecognised value may cause errors. We recommend adding a fallback handler for unknown enum values, so that any new value that does reach your integration degrades gracefully rather than failing.'
servers:
- url: https://api.goodstack.io
  description: Production server
- url: https://sandbox-api.goodstack.io
  description: Sandbox server
tags:
- name: Validation Request Documents
paths:
  /v1/validation-requests/{validationRequestId}/document:
    parameters:
    - in: path
      name: validationRequestId
      schema:
        type: string
      required: true
      description: Id of the Validation Request to add a document to
    post:
      security:
      - SecretApiKey: []
      summary: Create a Validation Request Document
      description: Uploads a document and updates the Validation Request to refer to that document. Valid file formats for documents are `jpg`, `png` and `pdf`. The maximum file size is 5MB. `heic`/`heif` photos are accepted too and are converted to `jpg` on upload.
      tags:
      - Validation Request Documents
      parameters:
      - in: header
        name: Idempotency-Key
        schema:
          type: string
        required: false
        description: Idempotency key
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Successfully uploaded document and updated Validation Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ValidationRequest'
                  object:
                    type: string
                    example: validation_request
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Idempotency.SameKeyDifferentData:
                  $ref: '#/components/examples/Idempotency.SameKeyDifferentData'
                MultipartBoundaryNotFound:
                  $ref: '#/components/examples/Upload.MultipartBoundaryNotFound'
                TooManyAttachments:
                  $ref: '#/components/examples/Upload.TooManyAttachments'
                ContentTypeError:
                  $ref: '#/components/examples/Upload.ContentTypeError'
                MaxFileSize:
                  $ref: '#/components/examples/Upload.MaxFileSize'
                FiletypeNotSupported:
                  $ref: '#/components/examples/Upload.FiletypeNotSupported'
                BadRequest:
                  $ref: '#/components/examples/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postV1ValidationRequestsByValidationRequestIdDocument
      x-operation-id-source: derived
components:
  examples:
    Upload.ContentTypeError:
      summary: Upload - Content type error
      description: Unsupported content type
      value:
        error:
          code: upload/content_type_error
          title: Bad request
          message: 'Unsupported content type: xls'
    Upload.MaxFileSize:
      summary: Upload - File exceeded max size
      description: File exceeded max size for this endpoint
      value:
        error:
          code: upload/max_file_size
          title: Bad request
          message: Request size exceeded maximum for this endpoint (5242880 bytes)
    BadRequest:
      summary: 400 Bad Request
      description: Bad Request
      value:
        error:
          code: bad_request
          title: Bad request
          message: Something is wrong with your request, please check any parameters and try again
    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
    Upload.MultipartBoundaryNotFound:
      summary: Upload - Multipart boundary not found
      description: Multipart boundary not found
      value:
        error:
          code: upload/multipart_boundary_not_found
          title: Bad request
          message: Please provide multipart boundary
    Upload.TooManyAttachments:
      summary: Upload - Too many attachments
      description: Too many files attached
      value:
        error:
          code: upload/too_many_files
          title: Bad request
          message: 'Too many files attached (max: 1)'
    Upload.FiletypeNotSupported:
      summary: Upload - Filetype not supported
      description: Filetype not supported
      value:
        error:
          code: upload/filetype_not_supported
          title: Bad request
          message: 'Filetype not supported.  Supported types include: pdf, png, jpg'
  schemas:
    ValidationRequestDocument:
      type: object
      properties:
        id:
          type: string
          example: validationrequestdocument_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        validationRequestId:
          type: string
          example: validationrequest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        url:
          type: string
          example: https://s3-eu-west-1.amazonaws.com/assets.poweredbypercent.com/document.docx
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            title:
              type: string
            message:
              type: string
            reasons:
              type:
              - array
              - 'null'
              items:
                type: string
    ValidationRequest:
      type: object
      properties:
        id:
          type: string
          example: validationrequest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name:
          type: string
          example: Some charity
        registryName:
          type: string
          example: National Charities Registry
        registryId:
          type: string
          example: I34324
          description: Charity's ID in registry
        email:
          type:
          - string
          - 'null'
          format: email
          example: test@percent.internal
        addressLine1:
          type:
          - string
          - 'null'
          example: Testowa street 15
        addressLine2:
          type:
          - string
          - 'null'
          example: Testowa street 22/15
        city:
          type:
          - string
          - 'null'
          example: Katowice
        postal:
          type:
          - string
          - 'null'
          example: 44-100
        state:
          type:
          - string
          - 'null'
          example: Silesia
        website:
          type: string
          format: website
          example: https://percent.internal
        organisationId:
          type:
          - string
          - 'null'
          example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        countryCode:
          type: string
          example: POL
        rejectionReason:
          type:
          - string
          - 'null'
          description: Reason for rejecting
          deprecated: true
          enum:
          - Organisation is not a nonprofit.
          - Organisation didn’t provide sufficient proof of nonprofit status.
          - Organisation is a nonprofit but doesn’t have an official registry ID.
          - Other
        rejectionReasonCode:
          type:
          - string
          - 'null'
          description: Reason code for rejecting
          enum:
          - other
          - not_eligible
          - incorrect_documentation
          - not_attributable_to_registry
        usaGroupExempt:
          type:
          - boolean
          - 'null'
          deprecated: true
        createdAt:
          type: string
          format: date-time
          example: '2020-10-13T17:46:54.000Z'
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-10-13T17:46:54.000Z'
        acceptedAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-10-13T17:46:54.000Z'
        rejectedAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-10-13T17:46:54.000Z'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/ValidationRequestDocument'
        organisationTypes:
          type: array
          items:
            type: string
            enum:
            - social_impact
            - nonprofit
  responses:
    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
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: unauthorized
                  title:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: Access is denied due to invalid credentials
    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
  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
    SCIMBearer:
      type: http
      scheme: bearer
      description: 'SCIM API key issued for the partner, presented as a bearer token in the

        `Authorization` header. The key is bound to a single partner and the

        partner must have the `scim_api` scope enabled. A missing or invalid key

        returns `401`; a valid key for a partner without the scope also returns

        `401` (`detail: "scim feature not enabled for this partner"`).

        '
x-tagGroups:
- name: NONPROFIT DATA
  tags:
  - Organisations
  - Countries
  - Registries
  - Categories
  - Organisation Branding
- 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
  - Monetary Donation Verifications
- name: WORKPLACE GIVING
  tags:
  - Employees
  - Giving Donations
  - Donation Match Request
  - Fundraising
  - Volunteering
  - Gamification
  - Campaigns
  - Budgets
  - Donation Wallets
- name: WEBHOOK SUBSCRIPTIONS
  tags:
  - Webhook Subscriptions
- name: WEBHOOK EVENTS
  tags:
  - Agent Verification Events
  - Country Compliance Check Events
  - Donation Events
  - Eligibility Subscription Events
  - Monitoring Subscription Events
  - Validation Request Events
  - Validation Submission Events
  - Monetary Donation Verification Events
x-provenance:
  method: harvested
  publisher: Goodstack
  source: https://reference.poweredbypercent.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)