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

## Create Your First Listing

A listing represents a business for sale on Venturu. Let's get one live!

## Quick Start

<Info>
  **Every listing created through the API needs a broker.** You can either reference an existing broker or create one inline with the listing. Both approaches work great!
</Info>

**Endpoint:** `PUT /partner/v1/listings/{externalListingId}`

<Steps>
  <Step title="Choose an External ID">
    Pick a unique ID from your system:

    * MLS number: `MLS-123456`
    * Database ID: `LISTING-789`
    * Custom format: `biz-miami-restaurant-001`

    <Warning>This ID is permanent - choose wisely!</Warning>
  </Step>

  <Step title="Link to a Broker">
    You have two options:

    <Tabs>
      <Tab title="Reference Existing Broker (Easier)">
        Use the broker's external ID:

        ```json theme={null}
        {
          "brokerExternalId": "BROKER-789",
          // ... rest of listing
        }
        ```
      </Tab>

      <Tab title="Create Broker Inline (Faster)">
        Include full broker data:

        ```json theme={null}
        {
          "broker": {
            "externalBrokerId": "BROKER-789",
            "name": "Jane Doe",
            "email": "jane@realestate.com"
          },
          // ... rest of listing
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add Business Details">
    ```json Minimum Required Fields theme={null}
    {
      "brokerExternalId": "BROKER-789",
      "status": "FOR_SALE",
      "businessType": "Restaurant",
      "location": {
        "city": "Miami",
        "state": "Florida",
        "country": "US",
        "visibility": "SHOW_CITY_STATE"
      }
    }
    ```
  </Step>

  <Step title="Send the Request">
    ```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 @listing.json
    ```
  </Step>

  <Step title="Success!">
    ```json theme={null}
    {
      "status": "success",
      "message": "Listing created successfully",
      "venturuListingId": 98765,
      "venturuListingUrl": "https://www.venturu.com/business/restaurant-miami-98765"
    }
    ```

    <Check>Listing is live! Buyers can now find it on Venturu.</Check>
  </Step>
</Steps>

## Complete Example

Here's a full listing with all the important fields:

<CodeGroup>
  ```json Complete Restaurant Listing theme={null}
  {
    "brokerExternalId": "BROKER-789",
    "status": "FOR_SALE",
    "title": "Profitable Downtown Pizzeria",
    "description": "Well-established pizzeria in the heart of downtown. Famous for authentic recipes and loyal customer base. Turnkey operation with fully equipped kitchen.",
    "businessType": "Restaurant",
    "establishedAt": "2010-05-15T00:00:00.000Z",
    
    "location": {
      "streetAddress1": "123 Main St",
      "city": "Miami",
      "state": "Florida",
      "postalCode": "33101",
      "country": "US",
      "visibility": "SHOW_FULL_ADDRESS"
    },
    
    "financials": {
      "askingPrice": 550000,
      "revenue": 800000,
      "sde": 220000,
      "inventory": 25000,
      "ffande": 150000
    },
    
    "property": {
      "propertyKind": "RENTED",
      "areaSqft": 2500,
      "rentData": {
        "amount": 5000,
        "frequency": "MONTHLY",
        "leaseRenewable": true,
        "leaseExpiration": "2028-12-31T00:00:00.000Z"
      }
    },
    
    "financing": {
      "financingAvailable": true,
      "sbaPrequalified": true,
      "minimumDownPayment": 100000
    },
    
    "photos": [
      {
        "url": "https://example.com/photos/storefront.jpg",
        "sortKey": 1
      },
      {
        "url": "https://example.com/photos/kitchen.jpg",
        "sortKey": 2
      }
    ]
  }
  ```

  ```bash cURL 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 @listing.json
  ```

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

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

  # Load your listing data
  with open('listing.json') as f:
      listing_data = json.load(f)

  response = requests.put(url, json=listing_data, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Essential Fields

<AccordionGroup>
  <Accordion title="Broker (Required)" icon="user">
    **Option 1:** Reference existing broker

    ```json theme={null}
    "brokerExternalId": "BROKER-789"
    ```

    **Option 2:** Create broker inline

    ```json theme={null}
    "broker": {
      "externalBrokerId": "BROKER-789",
      "name": "Jane Doe",
      "email": "jane@realestate.com"
    }
    ```
  </Accordion>

  <Accordion title="Status (Required)" icon="toggle-on">
    Controls visibility:

    * `FOR_SALE` - Live and searchable (use this!)
    * `DRAFT` - Not yet published
    * `ARCHIVED` - Temporarily hidden
    * `UNDER_CONTRACT` - Deal in progress
    * `SOLD` - Business sold

    See [Managing Listing Status](./managing-listing-status) for all options.
  </Accordion>

  <Accordion title="Business Type (Required)" icon="briefcase">
    The type of business:

    * `Restaurant`
    * `Retail`
    * `Service Business`
    * `E-commerce`
    * `Manufacturing`
    * And more...
  </Accordion>

  <Accordion title="Location (Required)" icon="map-pin">
    ```json theme={null}
    "location": {
      "city": "Miami",
      "state": "Florida",
      "country": "US",
      "visibility": "SHOW_CITY_STATE"
    }
    ```

    **Visibility options:**

    * `SHOW_FULL_ADDRESS` - Show complete address
    * `SHOW_CITY_STATE` - Show only city and state
    * `SHOW_STATE_ONLY` - Show only state
  </Accordion>
</AccordionGroup>

## Recommended Fields

<Tabs>
  <Tab title="Financials">
    ```json theme={null}
    "financials": {
      "askingPrice": 550000,
      "revenue": 800000,
      "sde": 220000,
      "inventory": 25000,
      "ffande": 150000
    }
    ```

    <Info>**SDE** = Seller's Discretionary Earnings. This is what most buyers care about!</Info>
  </Tab>

  <Tab title="Property">
    ```json theme={null}
    "property": {
      "propertyKind": "RENTED",
      "areaSqft": 2500,
      "rentData": {
        "amount": 5000,
        "frequency": "MONTHLY",
        "leaseExpiration": "2028-12-31T00:00:00.000Z"
      }
    }
    ```

    **Property Kind:**

    * `OWNED` - Business owns the property
    * `RENTED` - Business leases the property
    * `NEGOTIABLE` - Terms are flexible
  </Tab>

  <Tab title="Photos">
    ```json theme={null}
    "photos": [
      {
        "url": "https://example.com/photo1.jpg",
        "sortKey": 1
      },
      {
        "url": "https://example.com/photo2.jpg",
        "sortKey": 2
      }
    ]
    ```

    <Tip>
      **Pro tip:** Use 5-10 high-quality photos. Lower `sortKey` = appears first. Photos should be at least 1200px wide.
    </Tip>
  </Tab>

  <Tab title="Description">
    ```json theme={null}
    "title": "Profitable Downtown Pizzeria",
    "description": "A well-established pizzeria in the heart of downtown..."
    ```

    <Note>
      **Note:** We may optimize your description using AI to improve buyer engagement. Your original is always preserved.
    </Note>
  </Tab>
</Tabs>

## Common Questions

<AccordionGroup>
  <Accordion title="What if listing already exists?" icon="circle-question">
    No worries! If you use the same `externalListingId`, it will **update** instead of creating a duplicate. See [Updating a Listing](./updating-a-listing).
  </Accordion>

  <Accordion title="Can I create listing and broker together?" icon="circle-question">
    Yes! Use the inline `broker` object. Both will be created/updated in one API call.
  </Accordion>

  <Accordion title="How long until it appears on Venturu?" icon="circle-question">
    Instantly for `FOR_SALE` listings. We generate SEO-optimized URLs and descriptions in the background (takes \~1 minute).
  </Accordion>

  <Accordion title="What about draft listings?" icon="circle-question">
    Use `"status": "DRAFT"` to create without publishing. Change to `FOR_SALE` when ready. See [Managing Listing Status](./managing-listing-status).
  </Accordion>
</AccordionGroup>

## Next Steps

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

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

  <Card title="Create Broker" icon="user-plus" href="./creating-a-broker">
    Create a broker first
  </Card>

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