> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Request referral code

> Request a unique referral code for a customer. If the customer already has a code for this campaign, the existing code will be returned.



## OpenAPI

````yaml POST /customers/{id}/referrals/request-code
openapi: 3.0.1
info:
  title: Masivo's REST API
  description: Learn how to use Masivo's REST API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.masivo.ai/api/storefront/v1
security:
  - bearerAuth: []
paths:
  /customers/{id}/referrals/request-code:
    post:
      tags:
        - Referrals
      description: >-
        Request a unique referral code for a customer. If the customer already
        has a code for this campaign, the existing code will be returned.
      operationId: requestReferralCode
      parameters:
        - in: path
          name: id
          description: The customer unique identifier in your system
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - campaign_id
              properties:
                campaign_id:
                  type: string
                  format: uuid
                  description: The UUID of the referral campaign
                brand_id:
                  type: string
                  description: >-
                    The id of the brand. Required if the campaign is
                    brand-specific
                  nullable: true
                  x-default: null
            example: {}
      responses:
        '200':
          description: Referral code created or retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The unique identifier for this referral code record
                      code:
                        type: string
                        description: The unique referral code that can be shared
                        example: ZMQQJTAZ
                      customer_id:
                        type: string
                        description: The customer ID who owns this code
                      campaign_id:
                        type: string
                        format: uuid
                        description: The campaign ID this code belongs to
                      uses_count:
                        type: integer
                        description: Number of times this code has been successfully used
                      max_uses:
                        type: integer
                        description: Maximum number of times this code can be used
                      created_at:
                        type: string
                        format: date-time
                        description: Timestamp when the code was created
                      metadata:
                        type: object
                        description: Additional metadata for the referral code
                        nullable: true
        '404':
          description: Customer or campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid request or campaign not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      required:
        - error
        - details
      type: object
      properties:
        error:
          type: string
        details:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````