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

# Create Partner

> Create a new partnership and invite partner companies to collaborate

## Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.journeybee.io/api/v1/partnerships" \
    -H "Authorization: Bearer your-api-key-uuid" \
    -H "Content-Type: application/json" \
    -d '{"name": "Partner Company", "emails": [{"email": "contact@partner.com"}]}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.journeybee.io/api/v1/partnerships', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-api-key-uuid',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Partner Company",
      emails: [{ email: "contact@partner.com" }]
    })
  });
  ```
</CodeGroup>

## Request Body Schema

<ParamField body="name" type="string" required>
  The name of the partner company
</ParamField>

<ParamField body="emails" type="array" required>
  Array of contact email objects for the partner

  <Expandable title="Email Object">
    <ParamField body="email" type="string" required>
      Contact email address (must be valid business email)
    </ParamField>

    <ParamField body="firstName" type="string">
      Contact's first name
    </ParamField>

    <ParamField body="lastName" type="string">
      Contact's last name
    </ParamField>

    <ParamField body="tags" type="array">
      Array of tag IDs to assign to this contact
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="partnerType" type="string" required>
  Type of partnership. Options: `referral`, `reseller`
</ParamField>

<ParamField body="tierId" type="number">
  ID of the tier to assign to this partner
</ParamField>

<ParamField body="categoryId" type="number">
  ID of the category to assign to this partner
</ParamField>

<ParamField body="stageUuid" type="string">
  UUID of the stage to assign to this partner
</ParamField>

<ParamField body="inactive" type="boolean">
  Whether to create the partnership as inactive (won't send invites)
</ParamField>

<ParamField body="countryId" type="number">
  ID of the partner's country
</ParamField>

<ParamField body="emailDomain" type="string">
  Partner's email domain (auto-detected from email if not provided)
</ParamField>

<ParamField body="reseller" type="string">
  For reseller partnerships, specify who is the reseller. Options: `company`, `partner`
</ParamField>

<ParamField body="assignedUsers" type="array">
  Array of user IDs to assign to this partnership
</ParamField>

<ParamField body="tags" type="array">
  Array of tag IDs to assign to this partnership
</ParamField>

<ParamField body="customFields" type="array">
  Array of custom field values

  <Expandable title="Custom Field Object">
    <ParamField body="customFieldId" type="number" required>
      ID of the custom field
    </ParamField>

    <ParamField body="type" type="string" required>
      Field type: `text`, `textarea`, `number`, `date`, `boolean`, `select`, `multi_select`
    </ParamField>

    <ParamField body="value" type="object" required>
      Field value object matching the field type

      <Expandable title="Value Object Examples">
        <ParamField body="text" type="string">For text fields</ParamField>
        <ParamField body="number" type="number">For number fields</ParamField>
        <ParamField body="date" type="string">For date fields (ISO format)</ParamField>
        <ParamField body="boolean" type="boolean">For boolean fields</ParamField>
        <ParamField body="select" type="number">For select fields (option ID)</ParamField>
        <ParamField body="multi_select" type="array">For multi-select fields (array of option IDs)</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response Schema

The API returns a `201 Created` status code on success with no response body, but triggers the partnership creation and invitation flow.

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.journeybee.io/api/v1/companies/123/partnerships" \
    -H "Authorization: Bearer jb_api_1234567890abcdef" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "TechCorp Solutions",
      "emails": [
        {
          "email": "john@techcorp.com",
          "firstName": "John",
          "lastName": "Smith",
          "tags": [1, 2]
        }
      ],
      "partnerType": "referral",
      "tierId": 2,
      "categoryId": 3,
      "countryId": 1,
      "assignedUsers": [456],
      "tags": [10, 11],
      "customFields": [
        {
          "customFieldId": 5,
          "type": "number",
          "value": {
            "number": 100000
          }
        },
        {
          "customFieldId": 6,
          "type": "select",
          "value": {
            "select": 2
          }
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const partnerData = {
    name: "TechCorp Solutions",
    emails: [
      {
        email: "john@techcorp.com",
        firstName: "John",
        lastName: "Smith",
        tags: [1, 2]
      }
    ],
    partnerType: "referral",
    tierId: 2,
    categoryId: 3,
    countryId: 1,
    assignedUsers: [456],
    tags: [10, 11],
    customFields: [
      {
        customFieldId: 5,
        type: "number",
        value: {
          number: 100000
        }
      },
      {
        customFieldId: 6,
        type: "select",
        value: {
          select: 2
        }
      }
    ]
  };

  const response = await fetch('https://app.journeybee.io/api/v1/companies/123/partnerships', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer jb_api_1234567890abcdef',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(partnerData)
  });
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "status": "created",
    "message": "Partnership created successfully"
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid email format or missing required fields"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key or insufficient permissions"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 403 Forbidden theme={null}
  {
    "error": "Write access required for this operation"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 406 Not Acceptable theme={null}
  {
    "error": "Invalid email domains or attempting to partner with self"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 409 Conflict theme={null}
  {
    "error": "Partnership already exists with this company"
  }
  ```
</ResponseExample>

## Notes

* Requires API key with `write_access` permission
* All emails must be from the same business domain
* Triggers email invitations unless `inactive: true` is specified