GrowSurf Participant Rewards API

openapi: 3.2.0
info:
  title: GrowSurf REST Participant Rewards API
  version: 2.0.0
  description: 'Public GrowSurf REST API for managing programs, participants, referrals,

    rewards, affiliate commissions, payouts, and analytics.


    Every endpoint requires a GrowSurf REST API key in the `Authorization: Bearer `

    header. To get one, sign up at https://app.growsurf.com, then create an API key in the GrowSurf

    dashboard. You can create multiple API keys, with optional scopes and program access limits.


    Each operation lists its required API-key scope in `x-growsurf-required-scopes`.

    Team scopes cover team details and verification; program scopes cover program settings,

    reward configuration, and webhooks; participant scopes cover participant records and

    referrals; reward scopes cover sales, commissions, payouts, and issued rewards; and

    analytics scope covers aggregate reporting. `api_key:rotate` is available only to direct

    API-key REST/SDK clients and is unavailable through MCP. `reward:fulfill` is separate

    because fulfillment may deliver something of value.


    The team owner''s email address must be verified before the API can manage programs and their

    resources. Until it is, those endpoints return a `403` with error code

    `EMAIL_NOT_VERIFIED_ERROR`. Resend the owner verification email via

    `POST /team/owner/verification-email`, then retry.


    For agent-led onboarding, use the canonical Arazzo 1.1 workflow at

    `https://growsurf.com/arazzo.yaml`. Starting from an API key the account owner created, it

    configures and verifies a draft program. It never launches a program or performs a paid,

    reward, payout, key-rotation, or destructive action.


    REST responses include `RateLimit-Policy` and `RateLimit` fields so clients can throttle before

    they reach a quota. Before authentication, these fields describe only the caller''s public

    network budget. After authentication, they describe the credential and team budgets. A `429`

    response also includes `Retry-After`; that value takes precedence when it is present. GrowSurf''s

    legacy rate-limit fields remain available for backward compatibility.


    GrowSurf versions this API in the URL and gives at least 12 calendar months of public notice

    before a planned breaking removal. The notice period starts when the public OpenAPI schema marks

    the affected surface as deprecated and GrowSurf publishes migration guidance. Urgent security,

    privacy, legal, or service-integrity requirements can require a shorter window. See the public

    lifecycle policy for the full rules and machine-readable signals.


    Every REST response carries `Link: ; rel="deprecation"` (RFC 9745), which points at

    that lifecycle policy. A surface that is actually deprecated adds a `Deprecation` field, and one

    with a planned shutdown date adds a `Sunset` field (RFC 8594). No `Deprecation` field means the

    surface is not deprecated.'
  contact:
    name: GrowSurf Support
    url: https://growsurf.com/settings#contact_support
  license:
    name: Proprietary
    url: https://growsurf.com/terms
  x-deprecation-policy:
    url: https://docs.growsurf.com/developer-tools/rest-api/api-lifecycle
    versioning: URL path (/v2)
    minimumNoticeMonths: 12
    signals:
    - 'Link: <https://docs.growsurf.com/developer-tools/rest-api/api-lifecycle>; rel="deprecation" (RFC 9745) on every response'
    - Deprecation response field (RFC 9745) once a surface is deprecated
    - Sunset response field (RFC 8594) once a shutdown date is planned
    - 'deprecated: true in this OpenAPI document'
servers:
- url: https://api.growsurf.com/v2
  description: Production
security:
- apiKeyAuth: []
tags:
- name: Participant Rewards
  description: Participant reward retrieval and manual reward operations.
paths:
  /campaign/{id}/participant/{participantIdOrEmail}/rewards:
    get:
      tags:
      - Participant Rewards
      operationId: listParticipantRewards
      x-growsurf-required-scopes:
      - reward:read
      summary: List participant rewards
      description: Retrieves a paged list of rewards earned by a participant.
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - $ref: '#/components/parameters/ParticipantIdOrEmail'
      - $ref: '#/components/parameters/NextId'
      - $ref: '#/components/parameters/Limit100'
      responses:
        '200':
          description: Participant rewards returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantRewardListResponse'
              examples:
                default:
                  $ref: '#/components/examples/ParticipantRewardListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /campaign/{id}/reward/{rewardId}/approve:
    post:
      tags:
      - Participant Rewards
      operationId: approveParticipantReward
      x-growsurf-required-scopes:
      - reward:write
      x-growsurf-conditional-scopes:
      - condition: BODY_FULFILL_TRUE
        scopes:
        - reward:fulfill
      summary: Approve participant reward
      description: Approves a participant reward that requires manual approval. This requires `reward:write`. When the request also sets `fulfill` to `true`, it additionally requires `reward:fulfill`.
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - $ref: '#/components/parameters/RewardId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveRewardRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/InvalidState'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /campaign/{id}/reward/{rewardId}/fulfill:
    post:
      tags:
      - Participant Rewards
      operationId: fulfillParticipantReward
      x-growsurf-required-scopes:
      - reward:fulfill
      summary: Mark participant reward as sent
      description: Marks an approved participant reward as sent. This status does not confirm delivery.
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - $ref: '#/components/parameters/RewardId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/InvalidState'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /campaign/{id}/reward/{rewardId}:
    delete:
      tags:
      - Participant Rewards
      operationId: deleteParticipantReward
      x-growsurf-required-scopes:
      - reward:delete
      summary: Delete participant reward
      description: Removes a participant reward that requires manual approval and has not yet been approved.
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - $ref: '#/components/parameters/RewardId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/InvalidState'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ParticipantReward:
      type: object
      description: A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.
      required:
      - id
      - rewardId
      - status
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier of the participant's reward. This is different for every new reward the participant earns.
          example: prew_rr35mg
        rewardId:
          type: string
          readOnly: true
          description: The ID of the program `Reward` (`CampaignReward`) that this participant has earned.
          example: crew_c6w1qo
        status:
          $ref: '#/components/schemas/RewardStatus'
          readOnly: true
          description: The status of the participant's reward.
        unread:
          type: boolean
          readOnly: true
          description: '`true` if the participant has not yet seen the reward in a GrowSurf window.'
          example: true
        approved:
          type: boolean
          readOnly: true
          description: '`true` if the participant''s reward has been approved.'
          example: false
        approvedAt:
          type:
          - integer
          - 'null'
          format: int64
          readOnly: true
          description: The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards.
          example: null
        fulfilledAt:
          type:
          - integer
          - 'null'
          format: int64
          readOnly: true
          description: The date and time the reward was marked as sent for this participant (UTC milliseconds). `null` if it has not been marked as sent.
          example: null
        isReferrer:
          type: boolean
          readOnly: true
          description: '`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types).'
          example: true
        isAvailable:
          type: boolean
          readOnly: true
          description: '`true` if the reward is available for the participant to claim or redeem.'
          example: false
        isFulfilled:
          type: boolean
          readOnly: true
          description: '`true` if the participant''s reward has been marked as sent.'
          example: false
        referredId:
          type: string
          readOnly: true
          description: The ID of the friend that was referred.
          example: xh345d
        referrerId:
          type: string
          readOnly: true
          description: The ID of the participant that made the referral.
          example: f8g9nl
        amount:
          type:
          - number
          - 'null'
          readOnly: true
          description: What this reward is worth, in major units of `currencyISO`. GrowSurf reads the coupon, account credit, payout, or gift card that the connected provider confirmed for this reward. Without one, it uses the amount saved on the reward when it was earned (`rewardAmount`, or `referredRewardAmount` for a referred friend, from the Campaign Reward `metadata`). Later changes to the Campaign Reward or the integration do not change it. `null` for a percent-off coupon (see `percentOff`) and when the reward has no amount and currency pair.
          example: 10
        currencyISO:
          type:
          - string
          - 'null'
          readOnly: true
          description: The ISO 4217 currency code for `amount`. `null` whenever `amount` is `null`.
          example: USD
        percentOff:
          type:
          - number
          - 'null'
          readOnly: true
          description: The discount of a percent-off coupon, from `0` to `100` (for example, `20` for 20% off). `null` for every other reward. A reward has either `amount` or `percentOff`, never both.
          example: null
        amountSource:
          readOnly: true
          oneOf:
          - $ref: '#/components/schemas/ParticipantRewardAmountSource'
          - type: 'null'
          description: Where `amount` or `percentOff` comes from. `METADATA` means the amount saved on the reward when it was earned. Any other value names the provider whose saved record supplied it. `null` when both `amount` and `percentOff` are `null`.
        commissionStructure:
          readOnly: true
          oneOf:
          - $ref: '#/components/schemas/CommissionStructure'
          - type: 'null'
          description: The commission structure associated with this reward. Present only for affiliate programs.
    Error:
      type: object
      properties:
        name:
          description: Error name returned for the failed request.
          type: string
          example: BadRequestError
        code:
          description: Stable machine-readable error code.
          type: string
          example: BAD_REQUEST_ERROR
        message:
          description: Human-readable error message.
          type: string
          example: Invalid request. Request params are missing or are invalid
        errors:
          description: Optional validation details for specific request fields.
          type: array
          items:
            type: object
            additionalProperties: true
          example:
          - field: email
            message: Invalid email address.
        status:
          description: HTTP status code for the error.
          type: integer
          example: 400
        supportUrl:
          description: Support URL related to the error, when available.
          type: string
          format: uri
          example: https://app.growsurf.com/settings#contact_support
        policyName:
          description: Rate-limit policy name for `429` errors, when available.
          type: string
          example: minute
        level:
          description: Error severity level, when available.
          type: string
          example: error
        timestamp:
          description: When the error response was created.
          type: string
          format: date-time
          example: '2026-07-08T12:00:00.000Z'
      example:
        name: BadRequestError
        code: BAD_REQUEST_ERROR
        message: Invalid request. Request params are missing or are invalid
        status: 400
        supportUrl: https://app.growsurf.com/settings#contact_support
    ParticipantRewardListResponse:
      type: object
      required:
      - rewards
      - limit
      - nextId
      properties:
        rewards:
          description: Participant rewards returned for this page.
          type: array
          items:
            $ref: '#/components/schemas/ParticipantReward'
        limit:
          description: Maximum number of rewards requested for this page.
          type: integer
        nextId:
          description: Reward ID to pass as `nextId` for the next page, or `null` when there are no more results.
          type:
          - string
          - 'null'
    CommissionStructure:
      type: object
      description: The commission configuration for an affiliate reward. Present only for affiliate programs.
      properties:
        amount:
          type:
          - integer
          - 'null'
          minimum: 1
          maximum: 999999999999
          description: Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. The maximum is `100000000` (1,000,000.00) for USD, EUR, and GBP. `null` for percentage-based commissions.
          example: null
        amountISO:
          type:
          - string
          - 'null'
          description: ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions.
          example: null
        event:
          type:
          - string
          - 'null'
          enum:
          - CLICK
          - LEAD
          - SALE
          - null
          description: The event that generates a commission. Missing legacy values read as `SALE`.
          example: SALE
        type:
          type:
          - string
          - 'null'
          enum:
          - PERCENT
          - FIXED
          - null
          description: 'How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`).'
          example: PERCENT
        minPaidReferrals:
          type:
          - integer
          - 'null'
          description: The minimum number of paid referrals required before commissions are earned.
          example: 2
        holdDuration:
          type:
          - integer
          - 'null'
          description: Number of days a commission is held before it can be paid out.
          example: 30
        duration:
          type:
          - string
          - 'null'
          description: 'How long commissions continue to be earned for a referred customer: `FOREVER`, `REPEATING`, or `ONCE`. Only applies when `event` is `SALE`. `null` for `CLICK` and `LEAD` commissions, which pay once per event.'
          example: FOREVER
        durationInMonths:
          type:
          - integer
          - 'null'
          description: When `duration` is `REPEATING`, the number of months over which commissions are earned. `null` otherwise.
          example: null
        approvalRequired:
          type:
          - boolean
          - 'null'
          description: '`true` if commissions require manual approval before they can be paid out.'
          example: false
        percent:
          type:
          - number
          - 'null'
          description: The commission percentage, used when `type` is `PERCENT`.
          example: 25
        hasMaxAmount:
          type:
          - boolean
          - 'null'
          description: '`true` if a maximum commission amount cap is configured.'
          example: false
        maxAmount:
          type:
          - integer
          - 'null'
          description: The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set.
          example: null
        maxAmountISO:
          type:
          - string
          - 'null'
          description: The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided.
          example: null
        hasIntro:
          type:
          - boolean
          - 'null'
          description: '`true` if an introductory commission rate is configured. Only applies when `event` is `SALE`. Always `false` for `CLICK` and `LEAD` commissions, whose `intro*` fields are `null`.'
          example: false
        introType:
          type:
          - string
          - 'null'
          description: 'How the introductory commission is calculated: `PERCENT` or `FIXED`.'
          example: null
        introPercent:
          type:
          - number
          - 'null'
          description: The introductory commission percentage, used when `introType` is `PERCENT`.
          example: null
        introAmount:
          type:
          - integer
          - 'null'
          description: The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`.
          example: null
        introAmountISO:
          type:
          - string
          - 'null'
          description: The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided.
          example: null
        introDuration:
          type:
          - string
          - 'null'
          description: How long the introductory rate applies.
          example: null
        introDurationInMonths:
          type:
          - integer
          - 'null'
          description: When `introDuration` is repeating, the number of months the introductory rate applies.
          example: null
      additionalProperties: false
    SuccessResponse:
      type: object
      required:
      - success
      properties:
        success:
          description: Whether the request succeeded.
          type: boolean
    ParticipantRewardAmountSource:
      type: string
      description: Where a participant reward's `amount` or `percentOff` comes from.
      enum:
      - STRIPE
      - CHARGEBEE
      - RECURLY
      - CHARGIFY
      - PAYPAL
      - VENMO
      - TANGO_CARD
      - TREMENDOUS
      - XTRM
      - METADATA
      example: STRIPE
    RewardStatus:
      type: string
      enum:
      - PENDING
      - FULFILLED
      - CANCELLED
      description: The reward lifecycle state. `CANCELLED` means an unpaid `LEAD` reward was reversed before fulfillment.
      example: FULFILLED
    ApproveRewardRequest:
      type: object
      properties:
        fulfill:
          type: boolean
          default: false
          description: Set `true` to mark the reward as sent after approval.
  parameters:
    RewardId:
      name: rewardId
      in: path
      required: true
      description: Participant reward ID.
      schema:
        type: string
    NextId:
      name: nextId
      in: query
      required: false
      description: ID to start the next paged result set with.
      schema:
        type: string
    ParticipantIdOrEmail:
      name: participantIdOrEmail
      in: path
      required: true
      description: GrowSurf participant ID or URL-encoded participant email address.
      schema:
        type: string
    CampaignId:
      name: id
      in: path
      required: true
      description: GrowSurf program ID.
      schema:
        type: string
    Limit100:
      name: limit
      in: query
      required: false
      description: Number of results to return. Maximum 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  responses:
    UnprocessableEntity:
      description: Request is not valid for the current program or participant state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: The account's billing requirements for this action are not met.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests.
      headers:
        RateLimit-Policy:
          description: Named quota policies, quotas, and windows using the IETF RateLimit Structured Fields format.
          schema:
            type: string
          example: '"second";q=50;w=5, "minute";q=400;w=60, "hour";q=20000;w=3600'
        RateLimit:
          description: Remaining quota and reset time in seconds for the active policy or policies.
          schema:
            type: string
          example: '"second";r=0;t=30'
        Retry-After:
          description: Whole seconds to wait before retrying this request. This field takes precedence over RateLimit.
          schema:
            type: string
            pattern: ^[0-9]+$
          example: '30'
        GrowSurf-RateLimit-Second-Limit:
          description: Number of API requests allowed per second policy.
          schema:
            type: integer
        GrowSurf-RateLimit-Second-Remaining:
          description: Number of API requests remaining in the second policy.
          schema:
            type: integer
        GrowSurf-Retry-After-Second-Milliseconds:
          description: Milliseconds until the second policy window resets.
          schema:
            type: integer
        GrowSurf-RateLimit-Minute-Limit:
          description: Number of API requests allowed per minute policy.
          schema:
            type: integer
        GrowSurf-RateLimit-Minute-Remaining:
          description: Number of API requests remaining in the minute policy.
          schema:
            type: integer
        GrowSurf-Retry-After-Minute-Milliseconds:
          description: Milliseconds until the minute policy window resets.
          schema:
            type: integer
        GrowSurf-RateLimit-Hour-Limit:
          description: Number of API requests allowed per hour policy.
          schema:
            type: integer
        GrowSurf-RateLimit-Hour-Remaining:
          description: Number of API requests remaining in the hour policy.
          schema:
            type: integer
        GrowSurf-Retry-After-Hour-Milliseconds:
          description: Milliseconds until the hour policy window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Success:
      description: Success response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessResponse'
          example:
            success: true
    Forbidden:
      description: The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            emailNotVerified:
              summary: Account owner email verification is required
              value:
                name: EmailNotVerifiedError
                code: EMAIL_NOT_VERIFIED_ERROR
                message: The team owner email address must be verified to use this endpoint. Check the owner inbox, or resend it via POST /v2/team/owner/verification-email. Retry this request with the same API key once verified.
                status: 403
            missingCredential:
              summary: No API key reached the API
              value:
                name: NotAuthorizedError
                code: NOT_AUTHORIZED_ERROR
                message: 'No API key provided. Send it as an Authorization: Bearer header.'
                status: 403
            invalidCredential:
              summary: The API key was rejected
              value:
                name: NotAuthorizedError
                code: NOT_AUTHORIZED_ERROR
                message: The API key provided is not valid. It may have been rotated or revoked.
                status: 403
            notAuthorized:
              summary: The credential cannot perform this action
              value:
                name: NotAuthorizedError
                code: NOT_AUTHORIZED_ERROR
                message: You are not authorized to perform this action.
                status: 403
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidState:
      description: Resource is not in a state that permits this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  examples:
    ParticipantRewardListExample:
      value:
        limit: 2
        nextId: prew_v2qtfq
        rewards:
        - id: prew_rr35mg
          rewardId: crew_c6w1qo
          status: PENDING
          unread: true
          approved: false
          approvedAt: null
          fulfilledAt: null
          isReferrer: true
          isAvailable: false
          isFulfilled: false
          referredId: xh345d
          referrerId: f8g9nl
        - id: prew_oltj0s
          rewardId: crew_c6w1qo
          status: FULFILLED
          unread: false
          approved: true
          approvedAt: 1659453091744
          fulfilledAt: 1659453418901
          isReferrer: false
          isAvailable: true
          isFulfilled: true
          referredId: zyx765
          referrerId: f8g9nl
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'GrowSurf REST API key supplied as `Authorization: Bearer <api_key>`.'
externalDocs:
  description: GrowSurf REST API lifecycle, versioning, and deprecation policy
  url: https://docs.growsurf.com/developer-tools/rest-api/api-lifecycle