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

> Create a new lead with support for partnerships, campaigns, custom fields, and complex business flows

## Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.journeybee.io/api/v1/leads" \
    -H "Authorization: Bearer your-api-key-uuid" \
    -H "Content-Type: application/json" \
    -d '{"email": "lead@company.com", "company_name": "Lead Company"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.journeybee.io/api/v1/leads', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-api-key-uuid',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: "lead@company.com",
      company_name: "Lead Company"
    })
  });
  ```
</CodeGroup>

## Request Body Schema

### Basic Lead Information

<ParamField body="company_name" type="string">
  Lead company name
</ParamField>

<ParamField body="email" type="string">
  Lead contact email address
</ParamField>

<ParamField body="phone_number" type="string">
  Lead contact phone number
</ParamField>

<ParamField body="first_name" type="string">
  Lead contact first name
</ParamField>

<ParamField body="last_name" type="string">
  Lead contact last name
</ParamField>

<ParamField body="source" type="string">
  Lead source. Options: `manual`, `campaign`, `partnership`, `integration`, `lead_submission_form`
</ParamField>

### Association & Partnership Configuration

<ParamField body="associationType" type="string" required>
  Type of lead association. Options: `referral`, `reseller`, `campaigns`
</ParamField>

<ParamField body="companyCampaignId" type="number">
  Campaign ID if creating a campaign lead
</ParamField>

<ParamField body="partnershipLead" type="object">
  Partnership configuration for referral/reseller leads

  <Expandable title="Partnership Lead Object">
    <ParamField body="partnership_id" type="number" required>
      Partnership ID for the lead
    </ParamField>

    <ParamField body="partners_company_id" type="number" required>
      Partner company ID
    </ParamField>

    <ParamField body="company_partnerships_id" type="number" required>
      Company partnership relationship ID
    </ParamField>

    <ParamField body="sendToPartner" type="boolean">
      Whether to send this lead to the partner (for referral flows)
    </ParamField>

    <ParamField body="assignedFromPartnerLead" type="boolean">
      Whether this lead was assigned from a partner
    </ParamField>

    <ParamField body="formSubmissionLead" type="boolean">
      Whether this lead came from a form submission
    </ParamField>

    <ParamField body="formDirection" type="string">
      Form submission direction. Options: `claim`, `send`
    </ParamField>

    <ParamField body="partners_company_name" type="string">
      Partner company name (for fallback data)
    </ParamField>

    <ParamField body="partnerUsers" type="array">
      Array of partner user IDs to notify
    </ParamField>

    <ParamField body="sentBy" type="object">
      Information about who sent the lead

      <Expandable title="Sent By Object">
        <ParamField body="userId" type="number">Sending user ID</ParamField>
        <ParamField body="email" type="string">Sending user email</ParamField>
        <ParamField body="companyName" type="string">Sending company name</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Tags & Custom Fields

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

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

  <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
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="partnerCustomFields" type="array">
  Array of custom field values for the partner's copy of the lead

  <Expandable title="Partner 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
    </ParamField>
  </Expandable>
</ParamField>

### Attribution & Analytics

<ParamField body="attributions" type="array">
  Array of attribution data for lead tracking

  <Expandable title="Attribution Object">
    <ParamField body="id" type="number" required>
      Attribution source ID
    </ParamField>

    <ParamField body="attributedDate" type="string" required>
      Attribution date (ISO format)
    </ParamField>
  </Expandable>
</ParamField>

### Integration Support

<ParamField body="integrationName" type="string">
  Name of the integration that created this lead. Options: `Salesforce`, `Hubspot`, `Pipedrive`, `Slack`
</ParamField>

<ParamField body="integrationCustomFields" type="array">
  Custom fields from external integrations

  <Expandable title="Integration Custom Field Object">
    <ParamField body="uuid" type="string" required>
      Custom field UUID from integration
    </ParamField>

    <ParamField body="value" type="any" required>
      Field value from integration
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="powerups" type="object">
  Integration-specific data (e.g., CRM IDs)

  <Expandable title="Powerups Object">
    <ParamField body="pipedrive" type="object">
      Pipedrive integration data

      <Expandable title="Pipedrive Object">
        <ParamField body="person_id" type="number">Pipedrive person ID</ParamField>
        <ParamField body="organization_id" type="number">Pipedrive organization ID</ParamField>
        <ParamField body="deal_id" type="number">Pipedrive deal ID</ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response Schema

<ResponseField name="id" type="number">
  The created lead ID
</ResponseField>

<ResponseField name="uuid" type="string">
  The created lead UUID
</ResponseField>

<ResponseField name="partnershipLeadId" type="number">
  The partnership lead ID (if partnership lead was created)
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.journeybee.io/api/v1/leads" \
    -H "Authorization: Bearer jb_api_1234567890abcdef" \
    -H "Content-Type: application/json" \
    -d '{
      "company_name": "TechCorp Solutions",
      "email": "contact@techcorp.com",
      "phone_number": "+1-555-123-4567",
      "first_name": "John",
      "last_name": "Smith",
      "source": "partnership",
      "associationType": "referral",
      "partnershipLead": {
        "partnership_id": 456,
        "partners_company_id": 234,
        "company_partnerships_id": 789,
        "sendToPartner": true,
        "partnerUsers": [567, 890]
      },
      "tags": [10, 11],
      "customFields": [
        {
          "customFieldId": 5,
          "type": "number",
          "value": {
            "number": 100000
          }
        },
        {
          "customFieldId": 6,
          "type": "text",
          "value": {
            "text": "High-value prospect from referral"
          }
        }
      ],
      "attributions": [
        {
          "id": 3,
          "attributedDate": "2024-01-15T10:30:00Z"
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const leadData = {
    company_name: "TechCorp Solutions",
    email: "contact@techcorp.com",
    phone_number: "+1-555-123-4567",
    first_name: "John",
    last_name: "Smith",
    source: "partnership",
    associationType: "referral",
    partnershipLead: {
      partnership_id: 456,
      partners_company_id: 234,
      company_partnerships_id: 789,
      sendToPartner: true,
      partnerUsers: [567, 890]
    },
    tags: [10, 11],
    customFields: [
      {
        customFieldId: 5,
        type: "number",
        value: {
          number: 100000
        }
      },
      {
        customFieldId: 6,
        type: "text",
        value: {
          text: "High-value prospect from referral"
        }
      }
    ],
    attributions: [
      {
        id: 3,
        attributedDate: "2024-01-15T10:30:00Z"
      }
    ]
  };

  const response = await fetch('https://app.journeybee.io/api/v1/leads', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer jb_api_1234567890abcdef',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(leadData)
  });

  const createdLead = await response.json();
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 789,
    "uuid": "lead-uuid-789",
    "partnershipLeadId": 123
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid field values or missing required association"
  }
  ```
</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": "Missing required fields or invalid association type"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 409 Conflict theme={null}
  {
    "error": "Duplicate lead or unique constraint violation"
  }
  ```
</ResponseExample>

## Notes

* Requires API key with `write_access` permission
* Triggers real-time notifications and webhook events