GrowSurf Referrals and Invites API

openapi: 3.2.0
info:
  title: GrowSurf REST Referrals and Invites 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: Referrals and Invites
  description: Referral, invite, and participant email invite operations.
paths:
  /campaign/{id}/referrals:
    get:
      tags:
      - Referrals and Invites
      operationId: listReferrals
      x-growsurf-required-scopes:
      - participant:read
      summary: List referrals and invites
      description: Retrieves a list of all referrals and email invites made by participants in a program.
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - $ref: '#/components/parameters/ReferralSortBy'
      - $ref: '#/components/parameters/Desc'
      - $ref: '#/components/parameters/Limit100'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/ReferralEmailFilter'
      - $ref: '#/components/parameters/FirstNameFilter'
      - $ref: '#/components/parameters/LastNameFilter'
      - $ref: '#/components/parameters/ReferralStatusFilter'
      - $ref: '#/components/parameters/NextId'
      responses:
        '200':
          description: Referrals and invites returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralListResponse'
              examples:
                default:
                  $ref: '#/components/examples/ReferralListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /campaign/{id}/participant/{participantIdOrEmail}/referrals:
    get:
      tags:
      - Referrals and Invites
      operationId: listParticipantReferrals
      x-growsurf-required-scopes:
      - participant:read
      summary: List participant referrals and invites
      description: Retrieves referrals and email invites made by a participant.
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - $ref: '#/components/parameters/ParticipantIdOrEmail'
      - $ref: '#/components/parameters/ReferralSortBy'
      - $ref: '#/components/parameters/Desc'
      - $ref: '#/components/parameters/Limit100'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/ReferralEmailFilter'
      - $ref: '#/components/parameters/FirstNameFilter'
      - $ref: '#/components/parameters/LastNameFilter'
      - $ref: '#/components/parameters/ReferralStatusFilter'
      - $ref: '#/components/parameters/NextId'
      responses:
        '200':
          description: Participant referrals and invites returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralListResponse'
              examples:
                default:
                  $ref: '#/components/examples/ReferralListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /campaign/{id}/participant/{participantIdOrEmail}/invites:
    post:
      tags:
      - Referrals and Invites
      operationId: sendParticipantInvites
      x-growsurf-required-scopes:
      - participant:write
      summary: Send participant invites
      description: Sends email invites on behalf of a participant to a list of email addresses. Sending invites via the API requires a **verified custom email domain** on the program; the request fails until one is verified.
      parameters:
      - $ref: '#/components/parameters/CampaignId'
      - $ref: '#/components/parameters/ParticipantIdOrEmail'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendInvitesRequest'
            examples:
              default:
                value:
                  emailAddresses:
                  - erlich@aviato.com
                  subjectText: Join me on Pied Piper
                  messageText: '{{referrerFirstName}} invited you with {{referrerShareUrl}}.'
      responses:
        '200':
          description: Invite send result returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendInvitesResponse'
              examples:
                default:
                  value:
                    success: true
                    messageType: sent
                    invitesSent: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    ReferralStatusFilter:
      name: referralStatus
      in: query
      required: false
      description: Referral status to filter results.
      schema:
        $ref: '#/components/schemas/ReferralStatus'
    ReferralEmailFilter:
      name: email
      in: query
      required: false
      description: URL-encoded email value to filter referral results.
      schema:
        type: string
    NextId:
      name: nextId
      in: query
      required: false
      description: ID to start the next paged result set with.
      schema:
        type: string
    ReferralSortBy:
      name: sortBy
      in: query
      required: false
      description: Field used to sort referral results.
      schema:
        type: string
        enum:
        - updatedAt
        - createdAt
        - email
        - referralTriggeredAt
        default: updatedAt
    Offset:
      name: offset
      in: query
      required: false
      description: Offset number used to skip through a result set.
      schema:
        type: integer
        minimum: 0
        default: 0
    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
    FirstNameFilter:
      name: firstName
      in: query
      required: false
      description: First name value to filter results.
      schema:
        type: string
    LastNameFilter:
      name: lastName
      in: query
      required: false
      description: Last name value to filter results.
      schema:
        type: string
    Desc:
      name: desc
      in: query
      required: false
      description: Return results in descending order when true.
      schema:
        type: boolean
        default: true
    Limit100:
      name: limit
      in: query
      required: false
      description: Number of results to return. Maximum 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  examples:
    ReferralListExample:
      value:
        referrals:
        - id: f2bukr
          email: gavin@hooli.com
          firstName: Gavin
          lastName: Belson
          referralStatus: CREDIT_AWARDED
          referredBy: 2khaha
          createdAt: 1591546112223
          updatedAt: 1591546285013
        - id: ugqeq9
          email: '***************'
          firstName: null
          lastName: null
          referralStatus: INVITE_SENT
          referredBy: xde212
          createdAt: 1591469527740
          updatedAt: 1591469527740
        limit: 4
        nextOffset: 4
        nextId: g19s1b
        more: true
  schemas:
    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
    ReferralStatus:
      type: string
      enum:
      - CREDIT_PENDING
      - CREDIT_AWARDED
      - CREDIT_EXPIRED
      - INVITE_SENT
      example: CREDIT_AWARDED
    ReferralListResponse:
      type: object
      required:
      - referrals
      - limit
      - more
      properties:
        referrals:
          description: Referrals and invites returned for this page.
          type: array
          items:
            $ref: '#/components/schemas/Referral'
        limit:
          description: Maximum number of referrals requested for this page.
          type: integer
        nextOffset:
          description: Offset to pass as `offset` for the next page, or `null` when offset pagination is not used.
          type:
          - integer
          - 'null'
        nextId:
          description: Referral ID to pass as `nextId` for the next page, or `null` when there are no more results.
          type:
          - string
          - 'null'
        more:
          description: Whether another page of referrals is available.
          type: boolean
    SendInvitesRequest:
      type: object
      required:
      - emailAddresses
      - messageText
      - subjectText
      properties:
        emailAddresses:
          description: Email addresses to invite.
          type: array
          minItems: 1
          items:
            type: string
            format: email
          example:
          - erlich@aviato.com
        messageText:
          description: Message body for the invite email.
          type: string
          example: Try Pied Piper. I think you'll like the new compression workflow.
        subjectText:
          description: Subject line for the invite email.
          type: string
          example: Richard invited you to Pied Piper
    Referral:
      type: object
      required:
      - id
      - email
      - referralStatus
      - referredBy
      - createdAt
      - updatedAt
      properties:
        id:
          description: Participant ID for the referred friend or invitee.
          type: string
          example: f8g9nl
        email:
          description: Email address for the referred friend or invitee.
          type: string
          example: gavin@hooli.com
        firstName:
          description: First name for the referred friend or invitee.
          type:
          - string
          - 'null'
          example: Gavin
        lastName:
          description: Last name for the referred friend or invitee.
          type:
          - string
          - 'null'
          example: Belson
        referralStatus:
          description: Current referral status for this referred friend or invite.
          $ref: '#/components/schemas/ReferralStatus'
        referredBy:
          description: Participant ID of the referrer.
          type: string
          example: h8kp6l
        createdAt:
          description: When the referral or invite was created, as a Unix timestamp in milliseconds.
          type: integer
          format: int64
          example: 1719792000000
        updatedAt:
          description: When the referral or invite was last updated, as a Unix timestamp in milliseconds.
          type: integer
          format: int64
          example: 1719878400000
        referralTriggeredAt:
          description: When the referral was triggered, as a Unix timestamp in milliseconds. `null` until the referral is triggered, and for invites.
          type:
          - integer
          - 'null'
          format: int64
          example: 1719878400000
        referralCreditExpiredAt:
          description: When the referrer's credit for this referral expired, as a Unix timestamp in milliseconds. `null` when the credit has not expired.
          type:
          - integer
          - 'null'
          format: int64
          example: null
    SendInvitesResponse:
      type: object
      required:
      - success
      - messageType
      - invitesSent
      properties:
        success:
          description: Whether the invites request succeeded.
          type: boolean
        messageType:
          description: Result category for the invites request.
          type: string
          example: sent
        invitesSent:
          description: Number of invite emails sent.
          type: integer
          example: 1
  responses:
    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'
    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'
  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