GOOD Grants Grant statuses API

openapi: 3.2.0
info:
  title: Good Grants Grant statuses API
  version: '2.3'
  description: 'The Good Grants API enables you to programmatically manage grant-making programs, funding cycles, and application workflows.


    Use this API to:

    - Create and manage grant applications and submissions

    - Automate review workflows and scoring assignments

    - Track grant payments and fund allocations

    - Generate compliance reports and analytics

    - Integrate with external systems via webhooks


    All API requests require authentication using an API key provided in the `X-Api-Key` header.'
  license:
    name: Creative Force Client Subscription Terms
    url: https://creativeforce.team/agreement/
servers:
- url: https://api.us.cr4ce.com
  description: US regional endpoint
- url: https://api.eu.cr4ce.com
  description: EU regional endpoint
- url: https://api.au.cr4ce.com
  description: Australasia regional endpoint
- url: https://api.ca.cr4ce.com
  description: Canada regional endpoint
- url: https://api.hk.cr4ce.com
  description: Hong Kong regional endpoint
security:
- ApiKeyAuth: []
tags:
- name: Grant statuses
  description: 'Use these operations to retrieve custom grant lifecycle statuses.

    Grant statuses provide additional status tracking beyond standard application review statuses.


    These are used to track stages like "Eligibility Review", "Compliance Check", "Funding Approved", "Grant Agreement Signed".

    Note: Grant statuses are read-only via the API and must be configured through the Good Grants interface.'
paths:
  /grant-status:
    get:
      summary: List grant statuses
      operationId: GetGrantStatusCollectionV23
      tags:
      - Grant statuses
      parameters:
      - $ref: '#/components/parameters/grantStatusSlugFilter'
      - $ref: '#/components/parameters/deletedFilter'
      - $ref: '#/components/parameters/grantStatusOrder'
      - $ref: '#/components/parameters/sortDirection'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/perPage'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/X-Api-Language'
      responses:
        '200':
          description: Paginated list of grant statuses.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantStatusList'
            application/xml:
              schema:
                $ref: '#/components/schemas/GrantStatusList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      description: List grant statuses.
  /grant-status/{grant_status_slug}:
    get:
      summary: Get grant status
      operationId: GetGrantStatusV23
      tags:
      - Grant statuses
      parameters:
      - $ref: '#/components/parameters/grantStatusSlug'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/X-Api-Language'
      responses:
        '200':
          description: Grant status retrieved.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantStatus'
            application/xml:
              schema:
                $ref: '#/components/schemas/GrantStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      description: Get the grant status identified by the specified slug.
webhooks:
  grant-status-changed:
    post:
      summary: Grant status changed
      operationId: GrantStatusChangedWebhookV23
      x-products:
      - Good Grants
      tags:
      - Grant statuses
      parameters:
      - $ref: '#/components/parameters/Signature'
      security: []
      requestBody:
        $ref: '#/components/requestBodies/GrantStatusWebhook'
      responses:
        '200':
          description: Return any 2xx status code to acknowledge receipt of the event.
components:
  schemas:
    Forbidden:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 403
            maximum: 403
    NotFound:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 404
            maximum: 404
    GrantStatusList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/GrantStatus'
      example:
        current_page: 1
        data:
        - created: '2023-04-10T13:33:09Z'
          description:
            en_GB: <p>For grants that are currently in progress</p>
          grant_count: 42
          name:
            en_GB: In progress
          order: 1
          slug: mwGbVggp
          updated: '2026-01-08T13:10:51Z'
        - created: '2023-04-10T13:33:27Z'
          description:
            en_GB: For completed grants
          grant_count: 6
          name:
            en_GB: Completed
          order: 2
          slug: VgyLljqj
          updated: '2024-09-03T11:38:00Z'
        first_page_url: https://api.au.cr4ce.com/grant-status?per_page=10&page=1
        from: 1
        last_page: 1
        last_page_url: https://api.au.cr4ce.com/grant-status?per_page=10&page=1
        next_page_url: ''
        path: https://api.au.cr4ce.com/grant-status
        per_page: 10
        prev_page_url: ''
        to: 2
        total: 2
    BadRequest:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 400
            maximum: 400
    GrantStatus:
      title: Grant status
      description: Grant status used to track the funding-pipeline stage of grant applications.
      type: object
      properties:
        created:
          type: string
          format: date-time
          description: Date and time when the grant status was created.
        description:
          type: object
          description: Translated description of the grant status, keyed by locale code, and may contain HTML.
          additionalProperties:
            type: string
        grant_count:
          type: integer
          description: Number of applications currently assigned this grant status.
        name:
          type: object
          description: Translated name of the grant status, keyed by locale code.
          additionalProperties:
            type: string
        order:
          type: integer
          description: Position of the grant status in the manager-defined display order.
        slug:
          type: string
          description: URL-safe identifier of the grant status.
        updated:
          type: string
          format: date-time
          description: Date and time when the grant status was last updated.
      example:
        created: '2023-04-10T13:33:27Z'
        description:
          en_GB: For completed grants
        grant_count: 6
        name:
          en_GB: Completed
        order: 2
        slug: VgyLljqj
        updated: '2024-09-03T11:38:00Z'
    TooManyRequests:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 429
            maximum: 429
    Pagination:
      type: object
      title: Pagination
      properties:
        current_page:
          type: integer
          description: Number of the page returned by this response, starting at `1`.
        first_page_url:
          type: string
          description: URL of the first page in the result set, relative when the requested page is beyond the last page.
        from:
          type:
          - integer
          - 'null'
          description: Position of the first record on this page within the full result set, starting at `1`, or `null` when the requested page is beyond the last page.
        last_page:
          type: integer
          description: Total number of pages.
        last_page_url:
          type: string
          description: URL of the last page in the result set, relative when the requested page is beyond the last page.
        next_page_url:
          type: string
          description: URL of the next page in the result set, empty when the current page is the last page.
        path:
          type: string
          description: Canonical URL of the endpoint, without query parameters.
        per_page:
          type: integer
          default: 10
          description: Maximum number of records returned per page.
        prev_page_url:
          type: string
          description: URL of the previous page in the result set, empty when the current page is the first page.
        to:
          type:
          - integer
          - 'null'
          description: Position of the last record on this page within the full result set, or `null` when the requested page is beyond the last page.
        total:
          type: integer
          description: Total number of records across all pages.
    BaseProblem:
      description: Standard error envelope for all API error responses.
      type: object
      properties:
        message:
          type: string
        status_code:
          type: integer
          minimum: 400
          maximum: 599
    Unauthorized:
      allOf:
      - $ref: '#/components/schemas/BaseProblem'
      - type: object
        properties:
          status_code:
            type: integer
            minimum: 401
            maximum: 401
  parameters:
    grantStatusOrder:
      name: order
      in: query
      required: false
      description: Column name to order by. An unrecognised value falls back to the default sort by `updated`.
      schema:
        type: string
        enum:
        - created
        - grant_count
        - name
        - order
        - slug
        - updated
    sortDirection:
      name: dir
      in: query
      required: false
      description: Sort in ascending or descending order. Invalid values are rejected with `400 Bad Request`.
      schema:
        type: string
        enum:
        - asc
        - desc
    Accept:
      name: Accept
      in: header
      required: true
      description: Defines the response type.
      schema:
        type: string
        enum:
        - application/vnd.Creative Force.v2.3+json
        - application/vnd.Creative Force.v2.3+xml
    grantStatusSlugFilter:
      name: slug
      in: query
      required: false
      description: Filter to a single grant status by slug. Returns at most one item.
      schema:
        type: string
        pattern: ^[A-Za-z]{8}$
    grantStatusSlug:
      name: grant_status_slug
      in: path
      required: true
      description: Slug of the grant status.
      schema:
        type: string
        pattern: ^[A-Za-z]{8}$
    deletedFilter:
      name: deleted
      in: query
      required: false
      description: 'Filter by deletion mode.

        * `only` - Show only deleted resources.

        * `included` - Include deleted resources.

        * `none` - Exclude deleted resources.'
      schema:
        type: string
        enum:
        - only
        - included
        - none
    X-Api-Language:
      name: x-api-language
      in: header
      required: false
      description: 'Defines the languages included in the response. If non are provided, the account default language is returned.


        Value `all` overrides any other values present.


        You can request multiple languages using a comma-separated string of languages.


        The selected language must be supported by your account or a `400` error is returned.'
      style: simple
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
          - all
          - ar_AR
          - bg_BG
          - bn_IN
          - ca_ES
          - cs_CZ
          - cy_GB
          - da_DK
          - de_DE
          - en_GB
          - en_US
          - el_GR
          - es_NN
          - es_LA
          - et_EE
          - fa_NN
          - fi_FI
          - fr_FR
          - fr_CA
          - he_IL
          - hi_IN
          - hr_HR
          - hu_HU
          - hy_AM
          - it_IT
          - ja_JP
          - ko_KR
          - lt_LT
          - ms_MY
          - nl_NL
          - nb_NO
          - pl_PL
          - pt_BR
          - ro_RO
          - ru_RU
          - sk_SK
          - sl_SI
          - sq_AL
          - sr_RS
          - sv_SE
          - sw_NN
          - th_TH
          - tr_TR
          - uk_UA
          - vi_VN
          - zh_CN
          - zh_HK
      example:
      - en_GB
      - fr_FR
    perPage:
      name: per_page
      in: query
      required: false
      description: 'Limit the number of items returned to between 1 and 100.


        If you provide a value outside this range, you will receive a `400` response.

        '
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    Signature:
      name: Signature
      in: header
      required: true
      description: 'HMAC SHA256 signature of the request body. Generated using the webhook''s signing key and the raw JSON payload.


        Generate the same value in your endpoint and compare it with this header to validate the webhook payload.'
      schema:
        type: string
        example: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890
    page:
      name: page
      in: query
      required: false
      description: Specify the page number to return.
      schema:
        type: integer
        minimum: 1
        default: 1
  responses:
    NotFound:
      description: Resource identified by the path slug does not exist. Returned when the slug is well-formed but no record matches it.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
        application/xml:
          schema:
            $ref: '#/components/schemas/NotFound'
    ServiceUnavailable:
      description: Service is temporarily unavailable due to regional maintenance.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                description: Human-readable maintenance status.
            example:
              status: Maintenance in progress
        application/xml:
          schema:
            type: object
            properties:
              status:
                type: string
                description: Human-readable maintenance status.
            example:
              status: Maintenance in progress
    Unauthorized:
      description: Missing `x-api-key` header.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
        application/xml:
          schema:
            $ref: '#/components/schemas/Unauthorized'
    BadRequest:
      description: 'Request was rejected before the endpoint could process it. Common causes: invalid `Accept` header, unsupported `x-api-language` code, empty request body on `POST` / `PUT`, invalid JSON in the request body, or an invalid slug format in a path parameter.'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
        application/xml:
          schema:
            $ref: '#/components/schemas/BadRequest'
    TooManyRequests:
      description: Rate limit of 60 requests per minute exceeded.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequests'
        application/xml:
          schema:
            $ref: '#/components/schemas/TooManyRequests'
    Forbidden:
      description: 'Authenticated request denied. Common causes: invalid or unknown

        API key, suspended account, `api` feature not enabled for

        the account, or a read-only API key used for a request that

        is not a `GET`.'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Forbidden'
        application/xml:
          schema:
            $ref: '#/components/schemas/Forbidden'
  headers:
    X-RateLimit-Remaining:
      description: Number of requests remaining in the current rate limit window.
      schema:
        type: integer
        example: 58
    X-RateLimit-Limit:
      description: Maximum number of requests allowed per minute.
      schema:
        type: integer
        example: 60
    X-RateLimit-Reset:
      description: Unix timestamp when the rate limit window resets.
      schema:
        type: integer
        example: 1783470988
    Retry-After:
      description: Number of seconds the client should wait before retrying.
      schema:
        type: integer
      example: 60
    ETag:
      description: Entity tag for the selected representation.
      schema:
        type: string
  requestBodies:
    GrantStatusWebhook:
      description: Payload delivered for grant status-related events.
      required: true
      content:
        application/json:
          schema:
            type: object
            allOf:
            - type: object
              properties:
                applicant:
                  type: object
                  description: Applicant information.
                application_fields:
                  type: array
                  description: Custom form field values.
                grant_status:
                  type: object
                  description: Current grant status information.
                grant_start_date:
                  type: string
                  format: date-time
                  description: Grant start date.
                grant_end_date:
                  type: string
                  format: date-time
                  description: Grant end date.
                title:
                  type: string
                  description: Application title.
                slug:
                  type: string
                  description: Application slug.
                created:
                  type: string
                  format: date-time
                  description: Timestamp when the application was created.
                submitted:
                  type: string
                  format: date-time
                  description: Timestamp when the application was submitted.
                updated:
                  type: string
                  format: date-time
                  description: Timestamp when the application was last updated.
            - type: object
              properties:
                event:
                  type: string
                  description: Human-readable name of the event that triggered the webhook.
                  example: Grant status changed
                timestamp:
                  type: string
                  format: date-time
                  description: ISO 8601 formatted datetime indicating when the event occurred.
                  example: '2020-01-01T00:00:00Z'
                trigger:
                  type: string
                  description: Machine-readable event key that fired the webhook.
                  example: grant_status_changed
                source:
                  type: string
                  description: Origin of the change that triggered the event.
                  enum:
                  - ui
                  - api
                  default: ui
            example:
              applicant:
                slug: BwXxQawR
                link: https://api.au.cr4ce.com/user/BwXxQawR
                name: Jane Smith
                first_name: Jane
                last_name: Smith
              application_fields:
              - slug: IjKlMnOp
                link: https://api.au.cr4ce.com/field/IjKlMnOp
                label:
                  en_GB: <p>Outcomes achieved</p>
                title:
                  en_GB: Outcomes achieved
                value: Reached 120 beneficiaries across two regions.
              grant_status:
                slug: VgyLljqj
                name:
                  en_GB: Completed
                order: 2
              grant_start_date: '2026-12-30T00:00:00Z'
              grant_end_date: '2026-12-31T00:00:00Z'
              title: Project title
              slug: DeqEWpwO
              created: '2026-04-13T10:35:30Z'
              submitted: '2026-04-27T01:00:00Z'
              updated: '2026-06-18T07:25:20Z'
              event: Grant status changed
              timestamp: '2026-08-14T09:30:00Z'
              trigger: grant_status_changed
              source: ui
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key used to authenticate and authorise every request.

        Include it in the `x-api-key` header.'