Goodstack Organisations API

openapi: 3.2.0
info:
  title: Goodstack Services Organisations 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: Organisations
  description: Nonprofits are represented by the Organisation object. You can retrieve and query for Organisations.
paths:
  /v1/organisations:
    parameters:
    - in: query
      name: countryCode
      schema:
        type: string
      description: Filter search by three-letter ISO country code
    - in: query
      name: administrativeArea
      schema:
        type: string
      required: false
      description: 'Narrow results to an administrative area (state / province / county) within the `countryCode`, which is required when this is set. Send the area name — e.g. `California`, `Ontario`, `Kent`, `Aberdeen City`. US and Canada also accept a subdivision code (`US-CA`, `CA-ON`). Unrecognised values match nothing.

        '
    - in: query
      name: excludeCountryCodes
      schema:
        type: string
      required: false
      description: 'Comma-separated list of 3 character country codes to exclude from results. Only applies when countryCode is not provided (global search). Example: "CHN" or "CHN,IRN,PRK"

        '
    - in: query
      name: registryId
      schema:
        type: string
      description: Filter search using an organisation’s ID within their registry. Useful with usaGroupExempt param
    - in: query
      name: category[]
      schema:
        type: array
        items:
          type: string
          example: category_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      required: false
      description: Only return Organisations in the given Categories
      allowReserved: true
    - in: query
      name: notCategory[]
      schema:
        type: array
        items:
          type: string
          example: category_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      required: false
      description: Do not return Organisations in the given Categories
      allowReserved: true
    - in: query
      name: tags[]
      schema:
        type: array
        items:
          type: string
          example: aus-dgr1
      required: false
      description: Only return Organisations with the specified tags. To fetch organisations with tag X AND Y use the following `?tags[]=X&tags[]=Y`. To fetch organisations with tag X OR Y use the following `?tags[]=X,Y`. Currently supported tags are ind-fcra, aus-dgr1 and aus-dgr2.
      allowReserved: true
    - in: query
      name: notTags[]
      schema:
        type: array
        items:
          type: string
          example: aus-dgr4
      required: false
      description: Do not return Organisations with the specified tags. To fetch organisations with tag X AND NOT with Y use the following `?tags[]=X&notTags[]=Y`. To fetch organisations with not include tag X OR Y use the following `?notTags[]=X,Y`. To fetch organisations with not include tag X AND Y use the following `?notTags[]=X&notTags[]=Y`
      allowReserved: true
    - in: query
      name: type[]
      schema:
        type: array
        items:
          type: string
          enum:
          - nonprofit
      required: false
      description: Restrict search to a single type of organisation.
      allowReserved: true
    - in: query
      name: query
      schema:
        type: string
        example: cancer research
        maxLength: 500
      required: false
      description: Search for organisations by name. Must not exceed 500 characters or 512 bytes.
    - in: query
      name: lat
      schema:
        type: number
        example: 51.5074
        maximum: 90
        minimum: -90
      required: false
      description: Search for organisations by latitude. Must be between -90 and 90. Must be used with lon.
    - in: query
      name: lon
      schema:
        type: number
        example: -0.1278
        maximum: 180
        minimum: -180
      required: false
      description: Search for organisations by longitude. Must be between -180 and 180. Must be used with lat.
    - in: query
      name: distance
      schema:
        type: string
        example: 10km
        default: 100km
      required: false
      description: Search for organisations within a distance of a point. Can be used with lat and lon. The distance must be a number followed by a unit of measurement (km, m, mi, yd, ft, in, cm, mm, NM or nmi).
    - in: query
      name: usaGroupExempt
      schema:
        type: boolean
      description: Filter search by USA-specific group exempt. Recommended to use with registryId param
      required: false
    - in: query
      name: domain
      schema:
        type: string
      description: Filter search by domain of website or email
    - $ref: '#/components/parameters/page'
    - $ref: '#/components/parameters/pageSize'
    get:
      security:
      - PublishableApiKey: []
      summary: Search Organisations
      description: 'Search for nonprofits. The Organizations Search API provides up to 1,000 results for each search query, accessible via pagination.


        The exhaustiveTotalResults boolean field indicates whether the value of totalResults is exact (true) or approximate (false).

        If the system determines that the total number of results exceeds 10,000, the exhaustiveTotalResults field is set to false, indicating that totalResults is an approximation and that there are likely more than 10,000 results matching the query.


        If lat/lon coordinates are provided, the top results will be within the specified distance from this location, ranked by closeness. If lat/lon is provided without specifying a distance, a default of 100km will be used. Results outside of this radius this will be ranked by name match without consideration of distance.'
      tags:
      - Organisations
      responses:
        '200':
          description: Successfully retrieved a page of organisations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/Organisation'
                      - type: object
                        properties:
                          types:
                            type: array
                            items:
                              type: string
                              enum:
                              - nonprofit
                              - social_impact
                              - education
                          registryDetails:
                            allOf:
                            - $ref: '#/components/schemas/Registry'
                  totalResults:
                    type: integer
                    example: 33
                  pageNumber:
                    type: integer
                    example: 1
                  pageSize:
                    type: integer
                    example: 25
                  _links:
                    $ref: '#/components/schemas/OffsetLinks'
                  exhaustiveTotalResults:
                    type: boolean
                    description: whether the totalResults are exhaustive (true) or approximate (false)
                  object:
                    type: string
                    example: organisation
        '400':
          $ref: '#/components/responses/IncorrectParams'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
      operationId: getV1Organisations
      x-operation-id-source: derived
  /v1/organisations/{id}:
    parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: Id of the organisation
    get:
      security:
      - PublishableApiKey: []
      summary: Retrieve an Organisation
      tags:
      - Organisations
      responses:
        '200':
          description: Retrieve a nonprofit Organisation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                    - $ref: '#/components/schemas/Organisation'
                    - type: object
                      properties:
                        types:
                          type: array
                          items:
                            type: string
                            enum:
                            - nonprofit
                            - social_impact
                            - education
                        registryDetails:
                          allOf:
                          - $ref: '#/components/schemas/Registry'
                  object:
                    type: string
                    example: Organisation
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1OrganisationsById
      x-operation-id-source: derived
  /v1/organisations/{id}/milestones:
    parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: Id of the organisation
    get:
      security:
      - PublishableApiKey: []
      summary: List an Organisations Milestones
      tags:
      - Organisations
      responses:
        '200':
          description: Successfully list an Organisations milestones
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Milestone'
                  object:
                    type: string
                    example: milestone
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
      operationId: getV1OrganisationsByIdMilestones
      x-operation-id-source: derived
  /v1/organisations/{countryCode}/{registry}/{registryId}:
    parameters:
    - in: path
      name: countryCode
      schema:
        type: string
      description: 3 letter ISO-3166 alpha 3 identifier of the country
      required: true
    - in: path
      name: registry
      schema:
        type: string
      required: true
      description: Id of the registry
    - in: path
      name: registryId
      schema:
        type: string
      required: true
      description: Id of the Organisation within the registry
    get:
      security:
      - SecretApiKey: []
      summary: Retrieve an Organisation by country code, registry and registryId
      tags:
      - Organisations
      responses:
        '200':
          description: Retrieve a Organisation by country code, registry and registryId
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Organisation'
                  object:
                    type: string
                    example: Organisation
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1OrganisationsByCountryCodeByRegistryByRegistryId
      x-operation-id-source: derived
  /v1/organisations/{id}/profile:
    parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: Id of the organisation
    get:
      summary: Retrieve an Organisation profile info
      tags:
      - Organisations
      responses:
        '200':
          description: Retrieve a nonprofit Organisation profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Lemon rescue nonprofit
                      displayName:
                        type:
                        - string
                        - 'null'
                        example: Lemon Team
                      description:
                        type:
                        - string
                        - 'null'
                        example: Lemon Team
                      logo:
                        type:
                        - string
                        - 'null'
                        example: https://logo-url.com/the-logo.png
                      claimed:
                        type: boolean
                        example: true
                  object:
                    type: string
                    example: organisation_profile
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1OrganisationsByIdProfile
      x-operation-id-source: derived
components:
  schemas:
    Organisation:
      type: object
      properties:
        id:
          type: string
          example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name:
          type: string
          example: Green world
        displayName:
          type:
          - string
          - 'null'
          example: Green world
        description:
          type: string
          example: Environmental nonprofit supporting various types of wildlife across the northern and southern regions of the eastern southern hemisphere and australasia
        countryCode:
          type: string
          example: AUS
        milestones:
          type: array
          items:
            $ref: '#/components/schemas/Milestone'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        type:
          type: string
          deprecated: true
          enum:
          - nonprofit
        logo:
          type:
          - string
          - 'null'
          format: url
        images:
          type: array
          items:
            type: string
            format: url
        registry:
          type: string
          example: registry_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        registryId:
          type: string
          example: 12-3456789
        website:
          type:
          - string
          - 'null'
          example: https://example.com
        websites:
          type: array
          items:
            type: string
            example: https://example.com
        address:
          type:
          - string
          - 'null'
          example: 221b Baker Street, Westminster, London, NW1 6XE
        addressLine1:
          type:
          - string
          - 'null'
          example: 221b Baker Street
        addressLine2:
          type:
          - string
          - 'null'
          example: Westminster
        city:
          type:
          - string
          - 'null'
          example: London
        state:
          type:
          - string
          - 'null'
        postcode:
          type:
          - string
          - 'null'
          example: NW1 6XE
        registrationDate:
          type:
          - string
          - 'null'
          format: date-time
        registrationActive:
          type: boolean
          description: Whether the organisation's registration status is currently active
          example: true
        currencyCode:
          type:
          - string
          - 'null'
          example: AUD
        trustees:
          type:
          - string
          - 'null'
        claimedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        countrySpecificProperties:
          type: object
          deprecated: true
          properties:
            usaGroupExempt:
              type:
              - boolean
              - 'null'
              description: USA-specific group exempt
              deprecated: true
            fcra:
              type:
              - string
              - 'null'
              description: Foreign Contribution Regulation Act registration number for Indian organisations
              example: '123456789'
            DGR1:
              type:
              - boolean
              - 'null'
              description: Australian Deductible Gift Recipient (DGR) status - Item 1. Only present for Australian organisations
              example: true
            DGR2:
              type:
              - boolean
              - 'null'
              description: Australian Deductible Gift Recipient (DGR) status - Item 2. Only present for Australian organisations
              example: false
            DGR4:
              type:
              - boolean
              - 'null'
              description: Australian Deductible Gift Recipient (DGR) status - Item 4. Only present for Australian organisations
              example: true
        isBranchParent:
          type: boolean
          description: Whether this organisation is a parent of a branch
          example: false
        location:
          type:
          - object
          - 'null'
          properties:
            lat:
              type: number
              example: -33.86785
            lon:
              type: number
              example: 151.20732
    OffsetLinks:
      type: object
      properties:
        current:
          type: string
          example: https://.../v1/...?query=climate&page=4
        first:
          type: string
          example: https://.../v1/...?query=climate&page=1
        last:
          type: string
          example: https://.../v1/...?query=climate&page=9
        prev:
          type: string
          example: https://.../v1/...?query=climate&page=3
        next:
          type: string
          example: https://.../v1/...?query=climate&page=5
    Registry:
      type: object
      properties:
        id:
          type: string
          example: registry_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name:
          type: string
          example: Charity Registry
        englishName:
          type: string
          example: Charity Registry
        code:
          type: string
          example: CR
    Milestone:
      type: object
      properties:
        id:
          type: string
          example: milestone_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        amount:
          type: integer
          example: 1000
        reward:
          type: string
          example: This is a reward
        currencyCode:
          type: string
        organisationId:
          type: string
    Category:
      type: object
      properties:
        id:
          type: string
          example: category_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name:
          type: string
          example: Environmental
        imageUrl:
          type:
          - string
          - 'null'
          example: categories/3.png
        attributes:
          type:
          - object
          - 'null'
          additionalProperties:
            oneOf:
            - type: string
            - type: boolean
            - type: number
          description: A user-defined record of key-value pairs where the value can be a string, boolean, number, or null.
        createdAt:
          type: string
          format: date-time
          example: '2020-10-13T17:46:54.000Z'
  parameters:
    pageSize:
      in: query
      name: pageSize
      required: false
      schema:
        type: integer
        minimum: 0
        default: 25
      description: How many items per page, for pagination.
    page:
      in: query
      name: page
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number, for pagination.
  responses:
    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
    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)