---
openapi: 3.0.0
info:
  title: Propertybase API Suite
  description: 'Comprehensive API documentation for Propertybase integrations. Four
    core APIs work together: (1) Manda Middleware converts and delivers listings to
    property portals via API/FTP/Pickup; (2) Propertybase Ingestion API (PBPD) enables
    bulk object creation from external sources; (3) WebListings Query API (PBSE) retrieves
    live listing data for website display with search/filter/sort; (4) WebToProspect
    REST API (PBSE) captures leads from website forms with duplicate detection. All
    APIs support Bearer token and API key authentication.'
  version: 1.0.0
  license:
    name: Propertybase
  contact:
    name: Propertybase Support
    email: support@propertybase.com
servers:
- url: https://yourendpoint
  description: Your Propertybase webservice endpoint (Setup > Sites > Custom URLs)
- url: https://pb-integrations-api-staging.herokuapp.com
  description: Propertybase Ingestion API (staging)
- url: https://yoursitename.secure.force.com
  description: WebToProspect endpoint
paths:
  "/manda/portal-listings":
    get:
      tags:
      - Manda Middleware
      summary: Get Portal Listing status
      description: Query Portal Listing records to check publication status, delivery
        results, and error details. Portal Listings track the publishing workflow
        from Propertybase through Manda to destination portals.
      operationId: getPortalListings
      parameters:
      - name: listing_id
        in: query
        description: Filter by Listing ID
        schema:
          type: string
      - name: portal_id
        in: query
        description: Filter by Portal ID
        schema:
          type: string
      - name: status
        in: query
        description: Filter by status (Published, Failed, Pending, Withdrawn)
        schema:
          type: string
          enum:
          - Published
          - Failed
          - Pending
          - Withdrawn
      responses:
        '200':
          description: Portal Listing records
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PortalListing"
  "/pba__WebserviceListingsQuery":
    get:
      tags:
      - WebListings Query API
      summary: Query Propertybase listings
      description: Retrieve listings from Propertybase with filtering, sorting, and
        pagination. Returns XML or JSON.
      operationId: queryListings
      parameters:
      - name: token
        in: query
        description: Your webserviceWebListings_token
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Semicolon-separated field API names (e.g., name;pba__ListingPrice_pb__c;pba__Bedrooms_pb__c)
        required: true
        schema:
          type: string
      - name: itemsperpage
        in: query
        description: 'Number of results per page (default: 20, max: 1000)'
        schema:
          type: integer
          default: 20
      - name: page
        in: query
        description: Page number (0-indexed)
        schema:
          type: integer
          default: 0
      - name: orderby
        in: query
        description: Sort field and direction (e.g., pba__ListingPrice_pb__c;ASC)
        schema:
          type: string
      - name: getimages
        in: query
        description: Include image URLs
        schema:
          type: boolean
          default: false
      - name: getvideos
        in: query
        description: Include video URLs
        schema:
          type: boolean
          default: false
      - name: getdocuments
        in: query
        description: Include document URLs
        schema:
          type: boolean
          default: false
      - name: debugmode
        in: query
        description: Include debug messages in response
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful query response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebListingsResponse"
        '400':
          description: Invalid query parameters
        '401':
          description: Invalid or missing token
  "/services/apexrest/pba/webtoprospect/v1/":
    post:
      tags:
      - WebToProspect REST API
      summary: Create contact and inquiry
      description: Submit website leads to create contacts and inquiries in Propertybase.
        Supports duplicate detection.
      operationId: submitProspect
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/WebToProspectRequest"
      responses:
        '200':
          description: Prospect created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WebToProspectResponse"
        '400':
          description: Invalid request or missing required fields
        '401':
          description: Authentication failed
  "/api/v1/messages/{orgid}":
    post:
      tags:
      - Propertybase Ingestion API (PBPD)
      summary: Create bulk objects
      description: Write-only API for creating bulk objects (Leads, Contacts, Inquiries,
        etc.) in Propertybase
      operationId: bulkCreate
      parameters:
      - name: orgid
        in: path
        description: Your Propertybase organization ID
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/IngestionRequest"
      responses:
        '200':
          description: Objects created successfully
        '400':
          description: Invalid object or field
        '401':
          description: Invalid API key
components:
  schemas:
    WebListingsResponse:
      type: object
      properties:
        page:
          type: integer
          description: Current page number (0-indexed)
        listingsPerPage:
          type: integer
          description: Number of listings per page
        numberOfListings:
          type: integer
          description: Total listings matching filter
        fatalError:
          type: boolean
          description: Whether a fatal error occurred
        errorMessages:
          type: array
          items:
            type: string
          description: Any error messages
        debugMessages:
          type: array
          items:
            type: string
          description: Debug messages (if debugmode=true)
        listings:
          type: array
          items:
            "$ref": "#/components/schemas/Listing"
          description: Array of matching listings
    Listing:
      type: object
      properties:
        data:
          type: object
          description: Listing field data (fields vary by request)
          properties:
            id:
              type: string
              description: Listing record ID
            name:
              type: string
              description: Listing name/address
            pba__ListingPrice_pb__c:
              type: number
              description: Listing price
            pba__Bedrooms_pb__c:
              type: number
              description: Number of bedrooms
            pba__FullBathrooms_pb__c:
              type: number
              description: Number of bathrooms
        media:
          type: object
          properties:
            images:
              type: array
              items:
                "$ref": "#/components/schemas/MediaItem"
            videos:
              type: array
              items:
                "$ref": "#/components/schemas/MediaItem"
            documents:
              type: array
              items:
                "$ref": "#/components/schemas/MediaItem"
    MediaItem:
      type: object
      properties:
        title:
          type: string
        filename:
          type: string
        tags:
          type: string
        mimetype:
          type: string
        url:
          type: string
          format: uri
        baseurl:
          type: string
          format: uri
        external:
          type: boolean
          description: True if hosted externally (e.g., YouTube)
    WebToProspectRequest:
      type: object
      required:
      - prospect
      properties:
        prospect:
          type: object
          required:
          - contact
          properties:
            token:
              type: string
              description: Required for anonymous calls only
            contact:
              type: object
              required:
              - LastName
              properties:
                FirstName:
                  type: string
                LastName:
                  type: string
                Email:
                  type: string
                  format: email
                Phone:
                  type: string
                MobilePhone:
                  type: string
                OwnerId:
                  type: string
                  description: Salesforce User ID to assign record
            request:
              type: object
              description: Inquiry/search criteria data
              properties:
                pba__Bedrooms_pb_min__c:
                  type: number
                pba__Bedrooms_pb_max__c:
                  type: number
                pba__FullBathrooms_pb_min__c:
                  type: number
                pba__FullBathrooms_pb_max__c:
                  type: number
            favoriteListings:
              type: array
              items:
                type: string
              description: Array of listing IDs to link to inquiry
            contactFields:
              type: array
              items:
                type: string
              description: Contact fields to return in response
            requestFields:
              type: array
              items:
                type: string
              description: Inquiry fields to return in response
            ownerFields:
              type: array
              items:
                type: string
              description: Owner user fields to return in response
    WebToProspectResponse:
      type: object
      properties:
        errorMessage:
          type: string
          nullable: true
          description: Error message or null if successful
        contact:
          type: object
          description: Returned contact data
        request:
          type: object
          description: Returned inquiry data
        owner:
          type: object
          description: Returned owner user data
    IngestionRequest:
      type: object
      properties:
        object:
          type: string
          enum:
          - Lead
          - ContactForm
          - SavedSearch
          - PropertyView
          - Inquiry
          - EmailFriend
          - FavoriteProp
          - PropertyShowing
          - PropertyNote
        records:
          type: array
          items:
            type: object
    PortalListing:
      type: object
      description: Manda Portal Listing record tracking publication status and delivery
        results
      properties:
        Id:
          type: string
          description: Portal Listing record ID (pba__PortalListing__c)
        pba__Listing__c:
          type: string
          description: Reference to Listing record being published
        pba__Portal__c:
          type: string
          description: Reference to Portal configuration (defines delivery method,
            credentials, endpoint)
        pba__Status__c:
          type: string
          enum:
          - Published
          - Failed
          - Pending
          - Withdrawn
          description: Current publication status
        pba__ErrorMessage__c:
          type: string
          description: Detailed error message if rendering or delivery failed
        pba__DeliveryMethod__c:
          type: string
          enum:
          - API
          - FTP
          - Pickup
          description: How listing is delivered to portal
        pba__LastModifiedDate:
          type: string
          format: date-time
          description: Timestamp of last status update
        pba__RenderedOutput__c:
          type: string
          description: Format of rendered output (XML, JSON, or CSV)
    MandaPublishingWorkflow:
      type: object
      description: Manda Publishing Workflow - the 7-step process for listing publication
      properties:
        step_1_publish:
          type: string
          description: User publishes listing to portal in Propertybase UI
        step_2_send_to_manda:
          type: string
          description: Propertybase sends listing data and portal settings to Manda
            middleware
        step_3_render:
          type: string
          description: Manda converts listing to portal-required format (XML, JSON,
            or CSV). Missing fields and unsupported picklist values detected here.
        step_4_store_output:
          type: string
          description: Rendered feed is saved in the feed store for delivery or portal
            pickup
        step_5_status_writeback:
          type: string
          description: Manda writes result (success/validation error/delivery error)
            to Portal Listing record (pba__PortalListing__c)
        step_6_deliver:
          type: string
          description: Manda delivers listing by API push (real-time), scheduled FTP
            upload, or makes available for Pickup
        step_7_delete_handling:
          type: string
          description: Listing removal sends delete or withdrawn instruction to portal;
            may process even for inactive portals
    MandaPortalConfiguration:
      type: object
      description: Configuration required for Manda to publish to a portal
      required:
      - delivery_method
      - generator
      properties:
        delivery_method:
          type: string
          enum:
          - API
          - FTP
          - Pickup
          description: How Manda delivers the listing feed
        api_endpoint:
          type: string
          format: uri
          description: Portal API endpoint (required for API delivery)
        api_credentials:
          type: object
          description: Authentication for API delivery
          properties:
            api_key:
              type: string
            bearer_token:
              type: string
        ftp_host:
          type: string
          description: FTP server hostname (required for FTP delivery)
        ftp_username:
          type: string
          description: FTP authentication username
        ftp_password:
          type: string
          description: FTP authentication password
        ftp_path:
          type: string
          description: Directory path on FTP server for file upload
        ftp_schedule:
          type: string
          description: Scheduled upload frequency (e.g., daily, hourly)
        pickup_url:
          type: string
          format: uri
          description: URL where portal can download feed (required for Pickup delivery)
        generator:
          type: string
          description: Portal-specific renderer (e.g., 'MLS XML Renderer', 'Zillow
            JSON Renderer')
        output_format:
          type: string
          enum:
          - XML
          - JSON
          - CSV
          description: Portal-required output format
        field_mapping:
          type: object
          description: Maps Propertybase field names to portal field names
    MandaError:
      type: object
      description: Manda rendering or delivery error
      properties:
        error_code:
          type: string
          enum:
          - "[Listing invalid]"
          - "[FailedMapping]"
          - No FTP credentials
          - "[NoEndpoint]"
          - "[InvalidPicklistValue]"
        error_message:
          type: string
          description: Detailed error description
        field_name:
          type: string
          description: If applicable, the field causing the error
        solution:
          type: string
          description: Recommended corrective action
        timestamp:
          type: string
          format: date-time
          description: When error occurred
        listing_id:
          type: string
          description: ID of listing with error
        portal_id:
          type: string
          description: ID of portal configuration with error
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      description: Bearer token provided by Propertybase CS team
    ApiKey:
      type: apiKey
      in: query
      name: token
      description: API token as query parameter
security:
- BearerToken: []
- ApiKey: []
tags:
- name: WebListings Query API
  description: Query and retrieve Propertybase listings for display on websites
- name: WebToProspect REST API
  description: Create leads and inquiries from website forms with duplicate detection
- name: Propertybase Ingestion API (PBPD)
  description: Write-only API for bulk object creation
- name: Manda Middleware
  description: 'Manda is the internal middleware layer that automates portal publishing.
    It converts Propertybase listings into portal-specific formats (XML, JSON, CSV),
    handles field mapping and validation, and delivers via API (real-time push), FTP
    (scheduled upload), or Pickup (portal-initiated download). Manda tracks all publication
    status in Portal Listing records (pba__PortalListing__c). The 7-step publishing
    workflow: (1) User publishes in Propertybase, (2) Data sent to Manda, (3) Rendering
    to portal format, (4) Output stored in feed store, (5) Status written to Portal
    Listing, (6) Delivery via configured method, (7) Delete/withdrawn handling. Common
    errors include missing required fields, unsupported picklist values, broken field
    mappings, and missing FTP credentials.'