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

# Updating a Broker

## Update Broker Information

Need to change a broker's phone number? Update their bio? It's the same simple process.

<Info>
  **Same Endpoint:** Updating uses the exact same endpoint as creating. Just use the same `externalBrokerId` you used before.
</Info>

## How It Works

`PUT /partner/v1/brokers/{externalBrokerId}`

When you send a PUT request with an `externalBrokerId` that already exists, we update that broker with the new information.

<Steps>
  <Step title="Use the Same External ID">
    Use the exact same `externalBrokerId` you used when creating the broker.

    For example, if you created: `/brokers/BROKER-789`\
    To update, use: `/brokers/BROKER-789`
  </Step>

  <Step title="Send the Updated Data">
    Include all the fields you want to update. You can send:

    * **Just the changed fields** (recommended)
    * **All fields** (safest - ensures everything is in sync)

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

  <Step title="Get Confirmation">
    You'll receive a `200 OK` response (not `201` like creation):

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

## Common Update Scenarios

### Changing Contact Information

```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.new@realestate.com",
    "phone": "+1-555-9999"
  }'
```

### Adding or Updating Photo

```json theme={null}
{
  "name": "Jane Doe",
  "email": "jane@realestate.com",
  "avatarUrl": "https://example.com/photos/jane-new-headshot.jpg"
}
```

<Tip>
  When you update `avatarUrl`, we'll download and process the new image. It may take a few minutes to appear on the profile.
</Tip>

### Updating Bio and Social Links

```json theme={null}
{
  "name": "Jane Doe",
  "email": "jane@realestate.com",
  "profile": {
    "bio": "Award-winning business broker with 15+ years of experience. Specializing in restaurant acquisitions $500K-$5M.",
    "website": "https://janedoebroker.com",
    "linkedInUrl": "https://linkedin.com/in/jane-doe-broker"
  }
}
```

### Adding or Updating Licenses

```json theme={null}
{
  "name": "Jane Doe",
  "email": "jane@realestate.com",
  "licenses": [
    {
      "licenseNumber": "BK123456",
      "state": "Florida",
      "country": "US"
    },
    {
      "licenseNumber": "BK789012",
      "state": "Georgia",
      "country": "US"
    }
  ]
}
```

<Warning>
  **Important:** The `licenses` array replaces ALL existing licenses. Include all licenses you want the broker to have, not just new ones.
</Warning>

### Expanding Service Areas

```json theme={null}
{
  "name": "Jane Doe",
  "email": "jane@realestate.com",
  "serviceAreas": [
    {
      "city": "Miami",
      "state": "Florida",
      "country": "US"
    },
    {
      "city": "Fort Lauderdale",
      "state": "Florida",
      "country": "US"
    },
    {
      "county": "Broward County",
      "state": "Florida",
      "country": "US"
    }
  ]
}
```

<Warning>
  **Important:** The `serviceAreas` array replaces ALL existing areas. Include all areas you want to display.
</Warning>

## Best Practices

<CardGroup cols={2}>
  <Card title="Send Full Data" icon="database">
    When updating, send all fields (not just changed ones) to keep everything in perfect sync.
  </Card>

  <Card title="Sync Regularly" icon="arrows-rotate">
    Update broker profiles whenever data changes in your system to keep Venturu current.
  </Card>

  <Card title="Handle Errors" icon="triangle-exclamation">
    If an update fails, retry with exponential backoff. Updates are idempotent - safe to retry.
  </Card>

  <Card title="Monitor Responses" icon="chart-line">
    Track `200 OK` vs `201 Created` to see if you're accidentally creating duplicates.
  </Card>
</CardGroup>

## Partial Updates

You can update just specific fields if you prefer:

```json Only updating phone number theme={null}
{
  "name": "Jane Doe",
  "email": "jane@realestate.com",
  "phone": "+1-555-NEW-PHONE"
}
```

<Note>
  **Note:** While partial updates work, sending the complete broker object is safer and ensures data consistency across systems.
</Note>

## Common Questions

<AccordionGroup>
  <Accordion title="What happens if I use a new externalBrokerId?" icon="circle-question">
    You'll create a **new broker** instead of updating. Always use the same `externalBrokerId` for the same broker.
  </Accordion>

  <Accordion title="Can I update just the bio without sending other fields?" icon="circle-question">
    Yes, but you still need to include `name` and `email` (the required fields). Other fields will keep their existing values.
  </Accordion>

  <Accordion title="How often can I update a broker?" icon="circle-question">
    As often as you need! There are no rate limits on updates. Just be respectful of the API.
  </Accordion>

  <Accordion title="Do updates happen instantly?" icon="circle-question">
    Most updates are instant. Photos and some profile changes may take a few minutes to propagate.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Getting 404 Broker Not Found?

This means the `externalBrokerId` doesn't exist yet. Double-check:

1. You're using the correct external ID
2. The broker was created successfully
3. You're using the same partner API key

### Photo Not Updating?

Photos are processed asynchronously:

1. Wait 5-10 minutes
2. Clear your browser cache
3. Check that the image URL is publicly accessible
4. Ensure the image is at least 400x400px

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Listing" icon="building" href="./creating-a-listing">
    Create a listing for this broker
  </Card>

  <Card title="Update Listings" icon="pen" href="./updating-a-listing">
    Learn to update listings
  </Card>

  <Card title="Managing Status" icon="toggle-on" href="./managing-listing-status">
    Control listing visibility
  </Card>

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