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

# Core Concepts

Before you start integrating, understanding these core concepts will help you build a robust and reliable solution with the Venturu API.

## Idempotency

Our API is designed to be idempotent. This means that you can safely send the same request multiple times without creating duplicate entries or causing unintended side effects.

We achieve this by using the `PUT` HTTP method for both creating and updating resources like Brokers and Listings.

* **If you `PUT` data for an `externalId` that doesn't exist:** We create a new resource.
* **If you `PUT` data for an `externalId` that already exists:** We update the existing resource with the new information.

This makes your integration resilient. If a request fails due to a network error, you can simply retry it without worrying about creating duplicates.

<Tip>
  **Best Practice:** Design your sync jobs to be idempotent as well. This allows you to run them repeatedly without worrying about duplicates or inconsistent state.
</Tip>

## External IDs

You are the source of truth for your data. To keep our systems in sync, we rely on your unique identifiers. Throughout the API, you will see parameters like:

* `externalBrokerId`
* `externalListingId`

These are the unique IDs for brokers and listings **from your system**. You must provide these in the URL path when creating or updating a resource. We will store this ID and link it to the corresponding resource ID in Venturu's system.

This allows you to manage resources using the IDs you already know, without needing to store Venturu's internal IDs.

<Warning>
  **Important:** External IDs are permanent. Once you create a resource with an external ID, that ID will always refer to that specific resource. Don't reuse external IDs for different resources.
</Warning>

### Best Practices for External IDs

<CardGroup cols={2}>
  <Card title="Use Stable IDs" icon="anchor">
    Choose IDs that won't change over time. Database primary keys or MLS numbers are good choices.
  </Card>

  <Card title="URL-Safe Characters" icon="check">
    Stick to alphanumeric characters, hyphens, and underscores. Avoid spaces and special characters.
  </Card>

  <Card title="Consistent Format" icon="ruler">
    Use the same ID format across your integration for easier debugging and maintenance.
  </Card>

  <Card title="Document Your Mapping" icon="book">
    Keep a record of how your internal IDs map to Venturu external IDs.
  </Card>
</CardGroup>

## Flexible Resource Management

The Venturu API is designed to adapt to your workflow. When creating listings, you have two options for broker association:

1. **Reference by ID**: If you manage brokers separately, simply reference them using `brokerExternalId` when creating a listing
2. **Inline Creation**: Create or update both the broker and listing in a single API call by including the full broker object

This flexibility means you can choose the approach that best matches your system architecture:

* **Separate Management**: Ideal for systems where brokers are managed independently from listings (e.g., CRMs with distinct broker and listing modules)
* **Coupled Creation**: Perfect for syndication feeds where broker and listing data come together (e.g., MLS exports where both are in the same record)

<Info>
  Learn more about both approaches in the [Creating a Listing](../guides/creating-a-listing) guide.
</Info>

## Environments

The Venturu API provides two server environments. You can see these defined in our [OpenAPI specification](/openapi.json).

* **Production:** `https://www.venturu.com/api`

  This is the live environment. All data sent to this server will be visible on the public Venturu marketplace.

* **Local Development:** `http://localhost:3000/api`

  This URL is provided for our internal development and testing. As an external developer, you should always use the **Production URL**. We do not currently offer a public sandbox environment.

<Note>
  If you need a dedicated sandbox or staging environment for your integration, please contact [joel@venturu.com](mailto:joel@venturu.com) to discuss your requirements.
</Note>

## Next Steps

Now that you understand these core concepts, you're ready to start building your integration:

<CardGroup cols={2}>
  <Card title="Create a Broker" icon="user-plus" href="../guides/creating-a-broker">
    Get started by creating your first broker
  </Card>

  <Card title="Create a Listing" icon="circle-plus" href="../guides/creating-a-listing">
    Learn how to create business listings
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore all available endpoints
  </Card>

  <Card title="Venturu Marketplace" icon="globe" href="https://www.venturu.com">
    Visit the Venturu marketplace
  </Card>
</CardGroup>