> ## 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 Partner

> This endpoint creates a partner.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField body="first_name*" type="string">
  Partner's first name
</ParamField>

<ParamField body="last_name*" type="string">
  Partner's last name
</ParamField>

<ParamField body="email*" type="string">
  Partner's email address
</ParamField>

<ParamField body="program_id*" type="string">
  The program ID that the partner will belong to
</ParamField>

<ParamField body="group_id" type="string - optional">
  The group ID to assign the partner to
</ParamField>

<ParamField body="company_name" type="string - optional">
  Partner's company name
</ParamField>

<ParamField body="country_code" type="string - optional">
  Two-letter ISO country code of the partner
</ParamField>

<ParamField body="payout_method" type="string - optional">
  Partner's payout method. Valid values are: 'paypal', 'crypto', 'wise',
  'bank\_transfer', 'wire', 'none'
</ParamField>

<ParamField body="payout_details" type="object - optional">
  Details specific to the selected payout method (e.g., PayPal email, bank
  details)
</ParamField>

<ParamField body="notify_partner" type="boolean - optional">
  When true, sends a welcome email to the partner after their account is
  created.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array">
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="id" type="string">
      Unique identifier for the partner, `uuid` or prefixed with `part_`
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Partner's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Partner's last name
    </ResponseField>

    <ResponseField name="email" type="string">
      Partner's email address
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Partner's company name
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the partner belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>

    <ResponseField name="group_id" type="string">
      Group ID the partner belongs to
    </ResponseField>

    <ResponseField name="payout_method" type="string">
      Partner's payout method
    </ResponseField>

    <ResponseField name="payout_details" type="object">
      Payout method specific details
    </ResponseField>

    <ResponseField name="country_code" type="string">
      Two-letter ISO country code
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>

    <ResponseField name="completed_onboarding" type="boolean">
      The partner has completed onboarding.
    </ResponseField>

    <ResponseField name="rejection_note" type="string | null">
      A note why a partner was rejected.
    </ResponseField>

    <ResponseField name="internal_note" type="string | null">
      A note related to the partner.
    </ResponseField>

    <ResponseField name="suspension_reason" type="string | null">
      Reason for partner suspension if applicable.
    </ResponseField>

    <ResponseField name="first_customer_email_active" type="boolean">
      Whether first customer email notifications are active for this partner.
    </ResponseField>

    <ResponseField name="new_customer_email_active" type="boolean">
      Whether new customer email notifications are active for this partner.
    </ResponseField>

    <ResponseField name="payout_paid_email_active" type="boolean">
      Whether payout paid email notifications are active for this partner.
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

<ResponseField name="409 Conflict" type="object">
  Returned when a partner with the same email already exists in the program. The
  response includes the existing partner under `data`, so you can connect it to
  your system without a separate lookup.

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="success" type="boolean">
      Always `false` for errors.
    </ResponseField>

    <ResponseField name="error" type="string">
      `"Partner with this email already exists."`
    </ResponseField>

    <ResponseField name="data" type="object">
      The existing partner (same shape as a retrieved partner), including its `id`.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/partners' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "first_name": "Michael",
      "last_name": "Scott",
      "email": "michael.scott@dundermifflin.com",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "company_name": "Dunder Mifflin",
      "country_code": "US",
      "payout_method": "paypal",
      "payout_details": {
          "email": "michael.paypal@dundermifflin.com"
      }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "part_yP2D2oFyPsFUfkwzXCzRn3U2",
        "status": "active",
        "first_name": "TEST create",
        "last_name": "test",
        "company_name": null,
        "email": "aaaa@gmail.com",
        "program_id": "prg_ztTmEaAJRtfPVKM9nHhZwhjH",
        "organization_id": "org_qeHXERFhTv5DzxpvxtA5BWL5",
        "group_id": "grp_gMHPxVAQJghkdXSNXyQk6xfB",
        "created_at": "2025-08-06T13:46:07.328Z",
        "updated_at": "2025-08-06T13:46:07.328Z",
        "payout_method": "none",
        "payout_details": {},
        "country_code": null,
        "completed_onboarding": true,
        "rejection_note": null,
        "internal_note": null,
        "suspension_reason": null,
        "first_customer_email_active": true,
        "new_customer_email_active": true,
        "payout_paid_email_active": true
      }
    ]
  }
  ```

  ```json 409 Already exists theme={"system"}
  {
    "success": false,
    "error": "Partner with this email already exists.",
    "data": {
      "id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "first_name": "Michael",
      "last_name": "Scott",
      "email": "michael.scott@dundermifflin.com",
      "company_name": "Dunder Mifflin",
      "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
      "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
      "group_id": "grp_Zc2uw9zm1eyBiD3MHcjV3RDn",
      "payout_method": "paypal",
      "payout_details": {
        "email": "michael.paypal@dundermifflin.com"
      },
      "country_code": "US",
      "status": "active",
      "created_at": "2025-01-13T10:06:11.251Z",
      "updated_at": "2025-01-13T10:06:11.251Z"
    }
  }
  ```
</ResponseExample>