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

# Managing Listing Status

## Control Your Listing Visibility

Every listing has a `status` that controls whether it appears on Venturu. Let's make it simple.

## The Main Statuses

<CardGroup cols={2}>
  <Card title="FOR_SALE" icon="circle-check" color="#16a34a">
    **Live and searchable**\
    Appears in search results and on the marketplace
  </Card>

  <Card title="UNDER_CONTRACT" icon="file-signature" color="#f97316">
    **Sale in progress**\
    Shows "Under Contract" badge, removed from search
  </Card>

  <Card title="SOLD" icon="circle-dollar" color="#3b82f6">
    **Business has sold**\
    Marked as sold, removed from active search
  </Card>

  <Card title="ARCHIVED" icon="box-archive" color="#6b7280">
    **Temporarily hidden**\
    Not visible to buyers, but data is preserved
  </Card>

  <Card title="DRAFT" icon="circle-dashed" color="#94a3b8">
    **Not yet published**\
    For internal use, completely hidden
  </Card>

  <Card title="REVIEWING_OFFERS" icon="envelope-open-text" color="#8b5cf6">
    **Evaluating offers**\
    Still visible, indicates active negotiations
  </Card>
</CardGroup>

## Quick Reference

| Status             | Visible to Buyers? | In Search? | Use When                          |
| ------------------ | ------------------ | ---------- | --------------------------------- |
| `FOR_SALE`         | ✅ Yes              | ✅ Yes      | Ready to sell                     |
| `REVIEWING_OFFERS` | ✅ Yes              | ✅ Yes      | Have offers, still accepting more |
| `PENDING_CONTRACT` | ✅ Yes              | ✅ Yes      | Offer accepted, pending docs      |
| `UNDER_CONTRACT`   | ✅ Yes              | ✅ Yes      | Contract signed, in due diligence |
| `SOLD`             | ❌ No               | ❌ No       | Deal closed                       |
| `ARCHIVED`         | ❌ No               | ❌ No       | Temporarily off market            |
| `DRAFT`            | ❌ No               | ❌ No       | Still preparing                   |

## Changing Status

### Make a Listing Live

```bash theme={null}
curl -X PUT "https://www.venturu.com/api/partner/v1/listings/LISTING-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerExternalId": "BROKER-789",
    "status": "FOR_SALE",
    "businessType": "Restaurant",
    "location": {
      "city": "Miami",
      "state": "Florida",
      "country": "US",
      "visibility": "SHOW_CITY_STATE"
    }
  }'
```

<Check>Now live! Buyers can find and contact you about this listing.</Check>

### Mark as Under Contract

```bash theme={null}
curl -X PUT "https://www.venturu.com/api/partner/v1/listings/LISTING-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerExternalId": "BROKER-789",
    "status": "UNDER_CONTRACT"
  }'
```

<Info>Shows "Under Contract" badge. Deal is in progress, NOT removed from active search.</Info>

### Mark as Sold

```bash theme={null}
curl -X PUT "https://www.venturu.com/api/partner/v1/listings/LISTING-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerExternalId": "BROKER-789",
    "status": "SOLD",
  }'
```

<Check>Congratulations on the sale! The listing is now marked as sold.</Check>

### Archive (Temporarily Hide)

```bash theme={null}
curl -X PUT "https://www.venturu.com/api/partner/v1/listings/LISTING-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerExternalId": "BROKER-789",
    "status": "ARCHIVED",
    "businessType": "Restaurant",
    "location": {
      "city": "Miami",
      "state": "Florida",
      "country": "US",
      "visibility": "SHOW_CITY_STATE"
    }
  }'
```

<Info>**Archived!** The listing is hidden but all data is preserved. Change back to `FOR_SALE` anytime.</Info>

### Mark as Reviewing Offers

```bash theme={null}
curl -X PUT "https://www.venturu.com/api/partner/v1/listings/LISTING-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerExternalId": "BROKER-789",
    "status": "REVIEWING_OFFERS",
    "businessType": "Restaurant",
    "location": {
      "city": "Miami",
      "state": "Florida",
      "country": "US",
      "visibility": "SHOW_CITY_STATE"
    }
  }'
```

<Info>Still visible and searchable. Shows you're actively evaluating offers.</Info>

## Common Workflows

### Seller Pulls Listing Off Market

**Scenario:** Seller decides not to sell right now.

```json theme={null}
{
  "status": "ARCHIVED"
}
```

### You Have Interested Buyers

**Scenario:** Multiple offers coming in, still accepting more.

```json theme={null}
{
  "status": "REVIEWING_OFFERS"
}
```

### Offer Accepted, Pending Paperwork

**Scenario:** You've accepted an offer, waiting on signed contract.

```json theme={null}
{
  "status": "PENDING_CONTRACT"
}
```

### Contract Signed, In Due Diligence

**Scenario:** Contract is signed, buyer is doing their research.

```json theme={null}
{
  "status": "UNDER_CONTRACT"
}
```

### Deal Closes Successfully

**Scenario:** Transaction complete, business sold!

```json theme={null}
{
  "status": "SOLD"
}
```

### Deal Falls Through

**Scenario:** Pending deal didn't work out, back on market.

```json theme={null}
{
  "status": "FOR_SALE"
}
```

## Important Notes

<AccordionGroup>
  <Accordion title="FOR_SALE vs DRAFT" icon="circle-question">
    **DRAFT:** For new listings you're still preparing. Not visible anywhere.

    **FOR\_SALE:** For ready-to-show listings. Appears in search, gets traffic.

    <Tip>Start with `DRAFT`, switch to `FOR_SALE` when ready!</Tip>
  </Accordion>

  <Accordion title="Can I undo SOLD?" icon="circle-question">
    Yes! If a deal falls through, just change status back to `FOR_SALE` or `UNDER_CONTRACT`. No data is lost.
  </Accordion>

  <Accordion title="What's the difference between ARCHIVED and DRAFT?" icon="circle-question">
    **ARCHIVED:** Was active before, temporarily hidden (like "archiving")

    **DRAFT:** Never been active, still being prepared

    Both are hidden from buyers. Use whichever makes sense for your workflow!
  </Accordion>

  <Accordion title="Does UNDER_CONTRACT stop leads?" icon="circle-question">
    The listing is not removed from search. Leads may still come through the direct URL.
  </Accordion>

  <Accordion title="What about REVIEWING_OFFERS vs PENDING_CONTRACT?" icon="circle-question">
    **REVIEWING\_OFFERS:** You have offers but haven't accepted yet. Still accepting new offers.

    **PENDING\_CONTRACT:** You've accepted an offer, waiting for contract to be signed.

    Both are visible to buyers with appropriate badges.
  </Accordion>
</AccordionGroup>

## The Complete Status Flow

Here's the typical lifecycle of a listing:

```mermaid theme={null}
graph LR
    A[DRAFT] --> B[FOR_SALE]
    B --> C[REVIEWING_OFFERS]
    C --> D[PENDING_CONTRACT]
    D --> E[UNDER_CONTRACT]
    E --> F[SOLD]
    
    E -.-> B
    D -.-> B
    C -.-> B
    B --> G[ARCHIVED]
    G -.-> B
    
    style B fill:#16a34a
    style F fill:#3b82f6
    style G fill:#6b7280
```

**Solid arrows** = normal progression\
**Dotted arrows** = deal fell through, back to market

## Status Change Rules

<Note>
  **You can change between any statuses** at any time. The API doesn't enforce a specific workflow - use whatever makes sense for your business!
</Note>

Common transitions:

* `DRAFT` → `FOR_SALE` (publish for the first time)
* `FOR_SALE` → `REVIEWING_OFFERS` (offers coming in)
* `REVIEWING_OFFERS` → `PENDING_CONTRACT` (offer accepted)
* `PENDING_CONTRACT` → `UNDER_CONTRACT` (contract signed)
* `UNDER_CONTRACT` → `SOLD` (deal closed)
* `UNDER_CONTRACT` → `FOR_SALE` (deal fell through)
* `FOR_SALE` → `ARCHIVED` (seller changed mind)
* `ARCHIVED` → `FOR_SALE` (back on market)

## Bulk Status Updates

Need to change many listings at once? Just loop through them:

```python theme={null}
import requests

listings = ['LISTING-1', 'LISTING-2', 'LISTING-3']

for listing_id in listings:
    response = requests.put(
        f'https://www.venturu.com/api/partner/v1/listings/{listing_id}',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'brokerExternalId': 'BROKER-789',
            'status': 'ARCHIVED',  # Archive all
            'businessType': 'Restaurant',
            'location': {...}
        }
    )
    print(f'{listing_id}: {response.json()["message"]}')
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Data Current" icon="arrows-rotate">
    Update status as deals progress. Buyers appreciate accurate information.
  </Card>

  <Card title="Use REVIEWING_OFFERS" icon="handshake">
    Shows momentum and creates urgency for other buyers.
  </Card>

  <Card title="Don't Delete" icon="ban">
    Use `ARCHIVED` or `SOLD` instead of deleting. Preserves history and data.
  </Card>

  <Card title="Monitor Your Listings" icon="chart-line">
    Too many `FOR_SALE` listings? Consider archiving stale ones.
  </Card>
</CardGroup>

## Troubleshooting

### Status Not Changing?

Make sure you're including all required fields in your request:

* `brokerExternalId` or `broker` object
* `businessType`
* `location` object

### Invalid Status Error?

Check the spelling. Valid statuses are:

* `FOR_SALE`, `REVIEWING_OFFERS`, `PENDING_CONTRACT`, `UNDER_CONTRACT`, `SOLD`, `ARCHIVED`, `DRAFT`

### Listing Still Appearing?

Changes are instant, but:

* Clear your browser cache
* Wait \~1 minute for search index to update
* Check you used the correct `externalListingId`

## Next Steps

<CardGroup cols={2}>
  <Card title="Update Listing" icon="pen-to-square" href="./updating-a-listing">
    Change other listing details
  </Card>

  <Card title="Create Listing" icon="circle-plus" href="./creating-a-listing">
    Create a new listing
  </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 the API
  </Card>
</CardGroup>