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

# Get professional listing portfolio

> One fresh Property Finder UAE residential sale portfolio advertisement for this account’s unexpired professional observation. Limit 1, no cursor or extra selectors. Listing agent/broker identity must match the retained owner. Source asking AED price and coarse emirate only; no complete portfolio, current availability, sold-price comparable or source update-time claim. Contacts, precise location and photos omitted. Successful source call 50 credits; failures/replay zero.

<Note>Available for this account’s unexpired Property Finder UAE agency directory observation. One fresh residential sale portfolio advertisement, limit=1, no cursor. Success costs50 credits; failures and idempotent replay cost0.</Note>

Use the original professional ID from the same account. Missing, expired and unrelated-account IDs return404; schema-invalid limits return400 and unsupported cursors return422. Listing agent or broker identity must match the retained owner.

The listing has its own UAE emirate locality, source asking AED price, unknown status and unknown area basis. A Dubai professional may advertise in another emirate. Completeness and pagination totals remain unknown; no full portfolio, availability, sold-price comparable, valuation or source update-time claim. Contacts, exact location and photos are omitted. The returned listing ID supports ordinary account-owned listing reads for24 hours. See [coverage](/docs/coverage).


## OpenAPI

````yaml GET /v1/agencies/{agency_id}/listings
openapi: 3.1.0
info:
  title: RealtyCrawl proposed unified API
  version: 0.1.0
  description: >-
    Research draft dated 2026-10-13. No production server or enabled platform
    coverage is implied. Country and operation capabilities must be checked.
servers:
  - url: https://realtycrawl.dev
security:
  - ApiKeyAuth: []
paths:
  /v1/agencies/{agency_id}/listings:
    get:
      tags:
        - agencies
      summary: Get professional listing portfolio
      description: >-
        One fresh Property Finder UAE residential sale portfolio advertisement
        for this account’s unexpired professional observation. Limit 1, no
        cursor or extra selectors. Listing agent/broker identity must match the
        retained owner. Source asking AED price and coarse emirate only; no
        complete portfolio, current availability, sold-price comparable or
        source update-time claim. Contacts, precise location and photos omitted.
        Successful source call 50 credits; failures/replay zero.
      operationId: getAgencyListings
      parameters:
        - name: agency_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1
            default: 1
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response; meta discloses source completeness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getAgencyListingsResponse'
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    getAgencyListingsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - meta
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            details:
              type: array
              items:
                $ref: '#/components/schemas/SourceOutcome'
          required:
            - code
            - message
            - retryable
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    Listing:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        native_id:
          anyOf:
            - type: string
            - type: 'null'
        transaction:
          type: string
          enum:
            - sale
            - rent
            - lease
            - auction
        status:
          type: string
          enum:
            - active
            - pending
            - contingent
            - sold
            - rented
            - withdrawn
            - expired
            - off_market
            - unknown
        source_status:
          anyOf:
            - type: string
            - type: 'null'
        title:
          anyOf:
            - type: string
            - type: 'null'
        url:
          anyOf:
            - type: string
            - type: 'null'
        property:
          $ref: '#/components/schemas/PropertySummary'
        price:
          $ref: '#/components/schemas/Money'
        agent:
          anyOf:
            - $ref: '#/components/schemas/Agent'
            - type: 'null'
        agency:
          anyOf:
            - $ref: '#/components/schemas/Agency'
            - type: 'null'
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        observed_at:
          type: string
          format: date-time
        source_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        extensions:
          type: object
          properties: {}
          required: []
          additionalProperties: true
        field_status:
          type: object
          additionalProperties:
            type: string
            enum:
              - present
              - not_published
              - not_requested
              - unsupported
              - restricted
              - temporarily_unavailable
      required:
        - id
        - source
        - transaction
        - status
        - property
        - price
        - observed_at
      additionalProperties: false
    Meta:
      type: object
      properties:
        request_id:
          type: string
        schema_version:
          type: string
        generated_at:
          type: string
          format: date-time
        completeness:
          type: string
          enum:
            - complete
            - partial
            - unknown
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceOutcome'
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
            required:
              - code
              - message
            additionalProperties: false
        pagination:
          type: object
          properties:
            next_cursor:
              anyOf:
                - type: string
                - type: 'null'
            has_more:
              type: boolean
            returned:
              type: integer
            total:
              anyOf:
                - type: integer
                - type: 'null'
            total_relation:
              type: string
              enum:
                - exact
                - lower_bound
                - unknown
          required:
            - next_cursor
            - has_more
            - returned
            - total
            - total_relation
          additionalProperties: false
        property_groups:
          type: array
          items:
            $ref: '#/components/schemas/PropertyGroup'
      required:
        - request_id
        - schema_version
        - generated_at
        - completeness
        - sources
      additionalProperties: false
    SourceOutcome:
      type: object
      properties:
        platform:
          type: string
        provider:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - success
            - partial
            - failed
            - unsupported
        error_code:
          anyOf:
            - type: string
            - type: 'null'
        truncated:
          type: boolean
        observed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
      required:
        - platform
        - status
      additionalProperties: false
    Source:
      type: object
      properties:
        platform:
          type: string
        country:
          type: string
        native_id:
          anyOf:
            - type: string
            - type: 'null'
        url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
        provider:
          type: string
        observed_at:
          type: string
          format: date-time
        source_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        access_class:
          type: string
          enum:
            - public_portal
            - licensed_feed
            - public_record
            - modeled
        retrieved_at:
          type: string
          format: date-time
      required:
        - platform
        - provider
        - observed_at
        - access_class
      additionalProperties: false
    PropertySummary:
      type: object
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
        address:
          $ref: '#/components/schemas/Address'
        geometry:
          anyOf:
            - $ref: '#/components/schemas/Geometry'
            - type: 'null'
        property_type:
          type: string
        bedrooms:
          anyOf:
            - type: number
            - type: 'null'
        rooms:
          anyOf:
            - type: number
            - type: 'null'
        bathrooms:
          anyOf:
            - type: number
            - type: 'null'
        areas:
          type: array
          items:
            $ref: '#/components/schemas/Area'
        layout:
          anyOf:
            - type: string
            - type: 'null'
        year_built:
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - id
        - address
        - property_type
      additionalProperties: false
    Money:
      type: object
      properties:
        amount:
          anyOf:
            - type: string
              pattern: ^-?\d+(\.\d+)?$
            - type: 'null'
        min:
          anyOf:
            - type: string
            - type: 'null'
        max:
          anyOf:
            - type: string
            - type: 'null'
        currency:
          anyOf:
            - type: string
              pattern: ^[A-Z]{3}$
            - type: 'null'
        unit_code:
          anyOf:
            - type: string
            - type: 'null'
        kind:
          type: string
          enum:
            - asking
            - sold
            - rent
            - lease_rate
            - starting_bid
            - deposit
            - fee
            - estimate
            - unknown
        period:
          anyOf:
            - type: string
              enum:
                - night
                - week
                - month
                - year
                - one_time
            - type: 'null'
        per_area_unit:
          anyOf:
            - type: string
            - type: 'null'
        display_text:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - amount
        - currency
        - kind
      additionalProperties: false
    Agent:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        name:
          anyOf:
            - type: string
            - type: 'null'
        agency_id:
          anyOf:
            - type: string
            - type: 'null'
        profile_url:
          anyOf:
            - type: string
            - type: 'null'
        professional_contacts:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum:
                  - business_phone
                  - business_email
                  - website
              value:
                type: string
            required:
              - kind
              - value
            additionalProperties: false
        extensions:
          type: object
          properties: {}
          required: []
          additionalProperties: true
      required:
        - id
        - source
      additionalProperties: false
    Agency:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        name:
          anyOf:
            - type: string
            - type: 'null'
        address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
        website:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - source
      additionalProperties: false
    Media:
      type: object
      properties:
        url:
          type: string
          format: uri
        type:
          type: string
          enum:
            - photo
            - floor_plan
            - video
            - virtual_tour
            - document
        caption:
          anyOf:
            - type: string
            - type: 'null'
        position:
          type: integer
        source:
          $ref: '#/components/schemas/Source'
      required:
        - url
        - type
      additionalProperties: false
    PropertyGroup:
      type: object
      properties:
        property_id:
          anyOf:
            - type: string
            - type: 'null'
        listing_ids:
          type: array
          items:
            type: string
        match_method:
          type: string
        confidence:
          anyOf:
            - type: number
            - type: 'null'
        status:
          type: string
          enum:
            - matched
            - ambiguous
      required:
        - property_id
        - listing_ids
        - match_method
        - status
      additionalProperties: false
    Address:
      type: object
      properties:
        formatted:
          anyOf:
            - type: string
            - type: 'null'
        line1:
          anyOf:
            - type: string
            - type: 'null'
        unit:
          anyOf:
            - type: string
            - type: 'null'
        city:
          anyOf:
            - type: string
            - type: 'null'
        region:
          anyOf:
            - type: string
            - type: 'null'
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
        country:
          type: string
          pattern: ^[A-Z]{2}$
        original_text:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - country
      additionalProperties: false
    Geometry:
      type: object
      properties:
        latitude:
          type: number
          minimum: -90
          maximum: 90
        longitude:
          type: number
          minimum: -180
          maximum: 180
        precision:
          type: string
          enum:
            - exact
            - approximate
            - centroid
            - obfuscated
            - unknown
        crs:
          type: string
          const: EPSG:4326
      required:
        - latitude
        - longitude
        - precision
        - crs
      additionalProperties: false
    Area:
      type: object
      properties:
        value:
          type: number
        unit:
          type: string
          enum:
            - sqm
            - sqft
            - acre
            - hectare
            - ping
            - tsubo
            - other
        basis:
          type: string
          enum:
            - living
            - built
            - gross
            - carpet
            - saleable
            - land
            - unknown
        original_text:
          anyOf:
            - type: string
            - type: 'null'
        normalized_sqm:
          anyOf:
            - type: number
            - type: 'null'
      required:
        - value
        - unit
        - basis
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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