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

# Create or update by your id

> The recommended path for a CRM. If the id is new, the listing is created as in `POST /listings` (201). If known, the body applies as a `PATCH`: missing fields retain their value. The same body sent twice writes nothing (`X-Housera-Unchanged: true`).



## OpenAPI

````yaml en/openapi.json PUT /listings/ref/{ref}
openapi: 3.1.2
info:
  title: Housera API
  version: 1.0.0
  description: >-
    Publish and manage real estate listings on Housera from your CRM or
    application, with the same rules as the Housera form.
servers:
  - url: https://staging.housera.ro/api/v1
    description: 'Sandbox (staging): test data, the same rules as production.'
  - url: https://housera.ro/api/v1
    description: 'Production: real listings from housera.ro.'
security:
  - bearer: []
tags:
  - name: Your Listings
  - name: Photos
  - name: Events
  - name: Vocabulary
paths:
  /listings/ref/{ref}:
    put:
      tags:
        - Your Listings
      summary: Create or update by your id
      description: >-
        The recommended path for a CRM. If the id is new, the listing is created
        as in `POST /listings` (201). If known, the body applies as a `PATCH`:
        missing fields retain their value. The same body sent twice writes
        nothing (`X-Housera-Unchanged: true`).
      operationId: v1.listings.upsert
      parameters:
        - name: ref
          in: path
          required: true
          schema:
            type: string
          description: >-
            The listing ID in your system (up to 100 characters: letters,
            numbers, `.` `_` `:` `/` `-`).
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: 67211650-4dca-453c-b8c9-66321a61584d
          description: Successful.
        '201':
          content:
            application/json:
              schema:
                $ref: 67211650-4dca-453c-b8c9-66321a61584d
          description: The listing has been created and entered moderation.
        '202':
          content:
            application/json:
              schema:
                $ref: 67211650-4dca-453c-b8c9-66321a61584d
          description: 'Accepted: processing in the background.'
        '401':
          content:
            application/problem+json:
              schema:
                $ref: df9e5864-a2f9-487d-b0db-169bf3dc8506
          description: The key is missing, revoked, or expired (`unauthenticated`).
        '404':
          content:
            application/problem+json:
              schema:
                $ref: df9e5864-a2f9-487d-b0db-169bf3dc8506
          description: The listing does not exist or it is not your account (`not_found`).
        '409':
          content:
            application/problem+json:
              schema:
                $ref: df9e5864-a2f9-487d-b0db-169bf3dc8506
          description: >-
            The listing is occupied by another writing (`listing_busy`) or the
            action is not allowed in its state (`listing_action_refused`).
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.