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

# Create a partner

> Creates an onboarded partner together with their referral link. The link value defaults to a slug of the partner's name or email and the parameter to the program's first link parameter. Omit group_id to place the partner in the program's default group.



## OpenAPI

````yaml /api-reference/openapi.json post /v2/partners
openapi: 3.1.0
info:
  title: Tolt Public API
  version: 2.0.0
servers:
  - url: https://platform.tolt.dev
    description: Development
security:
  - bearerAuth: []
paths:
  /v2/partners:
    post:
      tags:
        - Partners
      summary: Create a partner
      description: >-
        Creates an onboarded partner together with their referral link. The link
        value defaults to a slug of the partner's name or email and the
        parameter to the program's first link parameter. Omit group_id to place
        the partner in the program's default group.
      operationId: createPartner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: >-
                    Partner's email address, where program emails such as the
                    welcome email go. It identifies the partner in the program,
                    so it cannot match another partner's email there, ignoring
                    case.
                  example: sam@acme.com
                program_id:
                  type: string
                  minLength: 1
                  description: >-
                    Id of the program to add the partner to (prg_...), as
                    returned when listing programs.
                  example: prg_YRsbPDAK
                first_name:
                  type: string
                  minLength: 1
                  maxLength: 150
                  description: >-
                    Partner's first name. With last_name it is used for the
                    default link value when link is omitted.
                  example: Sam
                last_name:
                  type: string
                  minLength: 1
                  maxLength: 150
                  description: >-
                    Partner's last name. With first_name it makes up the name
                    shown for the partner unless display_name is set.
                  example: Rivera
                display_name:
                  type: string
                  minLength: 1
                  maxLength: 150
                  description: >-
                    Overrides the name shown for the partner; defaults to the
                    first and last name.
                  example: Sam Rivera
                company_name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: >-
                    Business the partner promotes through, if they are a company
                    rather than a person. Leave it out for an individual.
                  example: Acme
                country_code:
                  type: string
                  pattern: ^[A-Za-z]{2}$
                  description: Two-letter ISO country code.
                  example: US
                website_url:
                  type: string
                  maxLength: 2048
                  format: uri
                  pattern: ^https?:\/\/[^\s/\\]\S*$
                  description: >-
                    URL of the partner's website, starting with http:// or
                    https://.
                  example: https://acme.com
                created_at:
                  type: string
                  format: date-time
                  description: Backdate the partner's creation time. Defaults to now.
                  example: '2024-01-15T10:00:00Z'
                group_id:
                  type: string
                  minLength: 1
                  description: >-
                    Group in the program. Defaults to the program's default
                    group.
                  example: grp_1a2b3c
                status:
                  type: string
                  enum:
                    - active
                    - pending
                  default: active
                  description: >-
                    Use pending to add the partner as an application that still
                    needs approval instead of an active partner.
                link:
                  type: object
                  properties:
                    value:
                      type: string
                      minLength: 1
                      maxLength: 100
                      description: >-
                        Slug that identifies the partner in referral URLs, such
                        as `sam` in `?ref=sam`. Pick one that no other link uses
                        with the same parameter.
                      example: sam
                    param:
                      type: string
                      minLength: 1
                      maxLength: 50
                      description: >-
                        Query parameter of the link, such as `ref` in
                        `?ref=sam`. Leave it out to use the program's first link
                        parameter.
                      example: ref
                  required:
                    - value
                  description: >-
                    The referral link created with the partner. Leave it out to
                    build the slug from the partner's name, or from the part of
                    the email before the @ when there is no name.
                notify_partner:
                  type: boolean
                  description: >-
                    Send the partner the program's welcome email. Only goes out
                    when the program's welcome email is enabled and the partner
                    is active.
                  example: true
              required:
                - email
                - program_id
              example:
                email: sam@example.com
                first_name: Sam
                last_name: Taylor
                program_id: prg_T6z8aRW3XCmvFWP972RKxpAd
                group_id: grp_zUQ8Pt281MsbNDApmDPN3Y2a
                link:
                  value: sam
                  param: ref
      responses:
        '201':
          description: The created partner with its referral link
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Request successful
                  data:
                    $ref: '#/components/schemas/CreatedPartner'
                required:
                  - success
                  - message
                  - data
              example:
                success: true
                message: Successfully created partner
                data:
                  id: part_NLYzgNKuSuASvrvoxNtau6SY
                  email: sam@example.com
                  first_name: Sam
                  last_name: Taylor
                  company_name: null
                  status: active
                  group_id: grp_zUQ8Pt281MsbNDApmDPN3Y2a
                  program_id: prg_T6z8aRW3XCmvFWP972RKxpAd
                  country_code: null
                  website_url: null
                  display_name: null
                  completed_onboarding: true
                  created_at: '2026-10-01T12:00:00Z'
                  updated_at: '2026-10-01T12:00:00Z'
                  rejected_at: null
                  suspended_at: null
                  link:
                    id: lnk_mtTeeckFa1vMdvDFXretQNs6
                    value: sam
                    param: ref
                    status: active
                    partner_id: part_NLYzgNKuSuASvrvoxNtau6SY
                    program_id: prg_T6z8aRW3XCmvFWP972RKxpAd
                    campaign_id: null
                    created_at: '2026-10-01T12:00:00Z'
                    updated_at: '2026-10-01T12:00:00Z'
          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'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: 'request: Invalid input: expected object, received null'
                code: validation_error
                doc_url: https://docs.tolt.com/errors#validation_error
                errors:
                  - field: request
                    message: 'Invalid input: expected object, received null'
          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'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: Unauthorized
                code: unauthorized
                doc_url: https://docs.tolt.com/errors#unauthorized
        '409':
          description: A partner with this email, or a link with this value, already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: A partner with this email already exists in the program
                code: already_exists
                doc_url: https://docs.tolt.com/errors#already_exists
                errors:
                  - field: email
                    message: A partner with this email already exists in the program
          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'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CreatedPartner:
      type: object
      properties:
        id:
          type: string
          example: part_NLYzgNKuSuASvrvoxNtau6SY
        email:
          type: string
          example: sam@example.com
        first_name:
          type:
            - string
            - 'null'
          example: Sam
        last_name:
          type:
            - string
            - 'null'
          example: Taylor
        company_name:
          type:
            - string
            - 'null'
          example: Sam's Studio
        status:
          type: string
          example: active
        group_id:
          type:
            - string
            - 'null'
          example: grp_zUQ8Pt281MsbNDApmDPN3Y2a
        program_id:
          type:
            - string
            - 'null'
          example: prg_T6z8aRW3XCmvFWP972RKxpAd
        country_code:
          type:
            - string
            - 'null'
          example: US
        website_url:
          type:
            - string
            - 'null'
          example: https://partner.example.com
        display_name:
          type:
            - string
            - 'null'
          description: Name shown for the partner in the dashboard.
          example: Sam Taylor
        completed_onboarding:
          type:
            - boolean
            - 'null'
          example: true
        created_at:
          type: string
          format: date-time
          example: '2026-10-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-10-01T12:00:00Z'
        rejected_at:
          anyOf:
            - type: string
              format: date-time
              example: '2026-10-01T12:00:00Z'
            - type: 'null'
          example: null
        suspended_at:
          anyOf:
            - type: string
              format: date-time
              example: '2026-10-01T12:00:00Z'
            - type: 'null'
          example: null
        link:
          $ref: '#/components/schemas/Link'
      required:
        - id
        - email
        - first_name
        - last_name
        - company_name
        - status
        - group_id
        - program_id
        - country_code
        - website_url
        - display_name
        - completed_onboarding
        - created_at
        - updated_at
        - rejected_at
        - suspended_at
        - link
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable explanation. May change; branch on code instead.
        code:
          type: string
          enum:
            - bad_request
            - validation_error
            - invalid_reference
            - invalid_cursor
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - already_exists
            - commission_paid
            - commission_frozen
            - transaction_refunded
            - commission_exists
            - rate_limited
            - payload_too_large
            - internal_error
          description: Stable machine-readable error code.
          example: not_found
        doc_url:
          type: string
          example: https://docs.tolt.com/errors#not_found
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
            required:
              - field
              - message
          description: >-
            One entry per offending field. Present on validation_error and
            invalid_reference.
      required:
        - success
        - message
        - code
        - doc_url
    Link:
      type: object
      properties:
        id:
          type: string
          example: lnk_mtTeeckFa1vMdvDFXretQNs6
        value:
          type:
            - string
            - 'null'
          example: sam
        param:
          type:
            - string
            - 'null'
          example: ref
        status:
          type:
            - string
            - 'null'
          example: active
        partner_id:
          type:
            - string
            - 'null'
          example: part_NLYzgNKuSuASvrvoxNtau6SY
        program_id:
          type:
            - string
            - 'null'
          example: prg_T6z8aRW3XCmvFWP972RKxpAd
        campaign_id:
          type:
            - string
            - 'null'
          example: null
        created_at:
          type: string
          format: date-time
          example: '2026-10-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-10-01T12:00:00Z'
      required:
        - id
        - value
        - param
        - status
        - partner_id
        - program_id
        - campaign_id
        - created_at
        - updated_at
  headers:
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix time, in seconds, when the window resets.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    PayloadTooLarge:
      description: Request body exceeds 1 MB
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Request body exceeds 1 MB
            code: payload_too_large
            doc_url: https://docs.tolt.com/errors#payload_too_large
    RateLimited:
      description: The API key exceeded its rate limit
      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'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Too many requests. Retry after the window resets.
            code: rate_limited
            doc_url: https://docs.tolt.com/errors#rate_limited
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tolt API key sent as a bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.