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

# Creating a Broker

## Create Your First Broker

Brokers are business professionals who list and sell businesses on Venturu. Every listing created through the API needs a broker, so let's create one.

## Quick Start

**Endpoint:** `PUT /partner/v1/brokers/{externalBrokerId}`

**What you need:**

* Your API key
* A unique ID from your system (like your broker's employee ID or email)
* Basic broker information (name, email)

<Steps>
  <Step title="Choose an External ID">
    Pick a stable, unique identifier from your system. Good choices:

    * Employee ID: `EMP-12345`
    * Email-based: `jane-doe`
    * Database ID: `broker-789`

    <Warning>This ID is permanent - once you use it, it always refers to this broker.</Warning>
  </Step>

  <Step title="Prepare Your Request">
    Create a JSON object with the broker's information:

    ```json theme={null}
    {
      "name": "Jane Doe",
      "email": "jane@realestate.com",
      "phone": "+1-555-0123"
    }
    ```
  </Step>

  <Step title="Send the Request">
    ```bash theme={null}
    curl -X PUT "https://www.venturu.com/api/partner/v1/brokers/BROKER-789" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Jane Doe",
        "email": "jane@realestate.com",
        "phone": "+1-555-0123"
      }'
    ```
  </Step>

  <Step title="Success!">
    You'll get back the broker's Venturu ID and profile URL:

    ```json theme={null}
    {
      "status": "success",
      "message": "Broker created successfully",
      "venturuBrokerId": "cmhnmzme1000b396q58yx17fm",
      "venturuProfileUrl": "https://www.venturu.com/u/jane-doe"
    }
    ```

    <Check>Broker created! They can now have listings assigned to them.</Check>
  </Step>
</Steps>

## Full Example with All Fields

Want to create a complete, professional profile? Here's an example with all optional fields:

<CodeGroup>
  ```json Complete Broker Profile theme={null}
  {
    "name": "Jane Doe",
    "email": "jane@realestate.com",
    "phone": "+1-555-0123",
    "avatarUrl": "https://example.com/photos/jane.jpg",
    "forwardingEmail": "leads-jane@crm.example.com",
    "profile": {
      "bio": "With over 10 years of experience in business brokerage, Jane specializes in restaurant and retail acquisitions.",
      "website": "https://janedoe.com",
      "linkedInUrl": "https://linkedin.com/in/janedoe"
    },
    "licenses": [
      {
        "licenseNumber": "BK123456",
        "state": "Florida",
        "country": "US"
      }
    ],
    "serviceAreas": [
      {
        "city": "Miami",
        "state": "Florida",
        "country": "US"
      }
    ]
  }
  ```

  ```bash cURL theme={null}
  curl -X PUT "https://www.venturu.com/api/partner/v1/brokers/BROKER-789" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d @broker.json
  ```

  ```python Python theme={null}
  import requests
  import os

  url = "https://www.venturu.com/api/partner/v1/brokers/BROKER-789"
  headers = {
      "Authorization": f"Bearer {os.getenv('VENTURU_API_KEY')}",
      "Content-Type": "application/json"
  }

  broker_data = {
      "name": "Jane Doe",
      "email": "jane@realestate.com",
      # ... rest of broker data
  }

  response = requests.put(url, json=broker_data, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://www.venturu.com/api/partner/v1/brokers/BROKER-789',
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${process.env.VENTURU_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Jane Doe',
        email: 'jane@realestate.com',
        // ... rest of broker data
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Field Reference

<AccordionGroup>
  <Accordion title="Required Fields" icon="asterisk">
    * **name**: Broker's full name
    * **email**: Primary email address (used for Venturu account)
  </Accordion>

  <Accordion title="Recommended Fields" icon="star">
    * **phone**: Contact number (include country code: `+1-555-0123`)
    * **avatarUrl**: Professional headshot (at least 400x400px)
    * **profile.bio**: Brief professional bio (2-3 sentences)
  </Accordion>

  <Accordion title="CRM Integration" icon="envelope">
    * **forwardingEmail**: Send leads directly to your CRM

    <Info>
      Many CRMs provide unique email addresses that automatically create leads. Set this field to pipe Venturu leads straight into your system!
    </Info>
  </Accordion>

  <Accordion title="Credentials & Areas" icon="map">
    * **licenses**: Array of license objects (`licenseNumber`, `state`, `country`)
    * **serviceAreas**: Where the broker operates (can specify by `city`, `county`, or `state`)
  </Accordion>

  <Accordion title="Social & Web" icon="link">
    * **profile.website**: Personal or company website
    * **profile.linkedInUrl**: LinkedIn profile URL
  </Accordion>
</AccordionGroup>

## Common Questions

<AccordionGroup>
  <Accordion title="What if the broker already exists?" icon="circle-question">
    No problem! If you use the same `externalBrokerId`, the broker will be **updated** instead of creating a duplicate. See [Updating a Broker](./updating-a-broker) for details.
  </Accordion>

  <Accordion title="Can I change the externalBrokerId later?" icon="circle-question">
    No - the `externalBrokerId` is permanent. It's the link between your system and Venturu. Choose wisely!
  </Accordion>

  <Accordion title="What about the broker's photo?" icon="circle-question">
    Provide a URL to the photo with `avatarUrl`. We'll download and optimize it. Photos are processed asynchronously, so they might not appear immediately.
  </Accordion>

  <Accordion title="How do leads get to my CRM?" icon="circle-question">
    Set the `forwardingEmail` field to your CRM's lead ingestion email. When someone contacts this broker on Venturu, we'll forward the lead there automatically.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Update Broker Info" icon="pen-to-square" href="./updating-a-broker">
    Learn how to update broker details
  </Card>

  <Card title="Create a Listing" icon="building" href="./creating-a-listing">
    Now create a listing for this broker
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full API documentation
  </Card>

  <Card title="Core Concepts" icon="book" href="../getting-started/core-concepts">
    Understanding external IDs
  </Card>
</CardGroup>