SkySlope Agents, Listings API

openapi: 3.2.0
info:
  title: SkySlope Offers API Reference Agents, Listings API
  x-logo:
    url: https://s3.amazonaws.com/cdn.skyslope.com/offer-management/om-logo-w-padding.png
    altText: Offers Logo
    href: https://skyslope.com/offer-management-login/
  description: '# Introduction

    The SkySlope Offers API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer).

    Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses,

    and uses standard HTTP response codes, authentication, and verbs.

    # Authentication

    The SkySlope Offers API uses [OAuth 2.0 client credentials flow](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/)

    to obtain an access token that can be used to authenticate subsequent API requests.


    To obtain an access token, see **[this endpoint](https://offers.skyslope.com/offers-api/reference#tag/Auth/paths/~1mls~1token/post)**.


    Authentication to the API is performed by including your access token in the **Authorization** header of your

    API requests with the Bearer authentication scheme.


    All API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). Calls made over plain HTTP will fail.

    API requests without authentication will also fail.

    '
  termsOfService: https://skyslope.com/terms-conditions/
  contact:
    name: Support
    url: https://support.skyslope.com/hc/en-us
    email: support@skyslope.com
servers:
- url: https://offers.skyslope.com/offers-api
  description: Production server
- url: https://staging-offers.skyslope.com/offers-api
  description: Staging server
tags:
- name: Agents, Listings
paths:
  /ext/agent/:agentId/listings?startDate=2023-01-01:
    get:
      summary: Retrieve an up-to-date agent listings & offers count
      description: 'Retrieve the ten listings owned by this agent, that have most recently received offers. Sorted descending by offer submission date (most recent first).

        '
      tags:
      - Agents, Listings
      parameters:
      - in: path
        name: agentId
        schema:
          type: string
          required: true
        description: 'The agent id used to filter the listings.  Contact SkySlope for your MLS field mapping.

          '
      - in: query
        name: startDate
        schema:
          type: Date
        required: false
        description: '<code>yyyy-mm-dd</code>

          <p>Optional parameter in ISO format <code>yyyy-mm-ddT00:00:00.000Z</code> to help separating listings with new offers from the rest.</p>

          <p>If <code>startDate</code> is not provided, it''s assumed to be 7 days prior to today.</p>

          <p>If there exists listings with offers newer than <code>startDate</code>, the <code>hasNewOffers</code> indicator will be true otherwise false.</p>

          '
      - in: header
        name: Authorization
        schema:
          type: string
        required: true
        description: '<code>Bearer ACCESS_TOKEN</code>


          <p>"ACCESS_TOKEN" is the token returned from /ext/token</p>

          '
      x-codeSamples:
      - lang: cURL
        source: 'curl -X GET "https://offers.skyslope.com/offers-api/ext/agent/:agentId/listings?startDate=2023-01-01" -H "Authorization: Bearer ACCESS_TOKEN"

          '
      - lang: Javascript
        source: "fetch(\"https://offers.skyslope.com/offers-api/ext/agent/:agentId/listings?startDate=2023-01-01\", {\n  headers: {\n    \"Authorization\": \"ACCESS_TOKEN\"\n  }\n})\n.then(response => {\n  console.info(response);\n})\n.catch(error => {\n  console.error(error);\n});\n"
      - lang: Python
        source: 'import requests


          url = "https://offers.skyslope.com/offers-api/ext/report"

          params = {"startDate": "2023-01-01", "endDate": "2023-04-26"}

          headers = {"Authorization": "ACCESS_TOKEN"}


          response = requests.get(url, params=params, headers=headers)

          print(response.content.decode())

          '
      - lang: C#
        source: "using System;\nusing System.Net.Http;\nusing System.Threading.Tasks;\n\nclass Program\n{\n    static async Task Main(string[] args)\n    {\n        using (var client = new HttpClient())\n        {\n            client.DefaultRequestHeaders.Add(\"Authorization\": \"ACCESS_TOKEN\");\n            var response = await client.GetAsync(\"https://offers.skyslope.com/offers-api/ext/agent/:agentId/listings?startDate=2023-01-01\");\n            Console.WriteLine(await response.Content.ReadAsStringAsync());\n        }\n    }\n}\n"
      - lang: PHP
        source: '$ch = curl_init();

          curl_setopt($ch, CURLOPT_URL, "https://offers.skyslope.com/offers-api/ext/agent/:agentId/listings?startDate=2023-01-01");

          curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization": "ACCESS_TOKEN"));

          curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

          $response = curl_exec($ch);

          curl_close($ch);


          echo $response;

          '
      - lang: Ruby
        source: 'require ''uri''

          require ''net/http''


          url = URI("https://offers.skyslope.com/offers-api/ext/agent/:agentId/listings?startDate=2023-01-01")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true


          request = Net::HTTP::Get.new(url)

          request["Authorization"] = "ACCESS_TOKEN"


          response = http.request(request)

          puts response.read_body

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasNewOffers:
                    type: boolean
                  listings:
                    type: array
                    items:
                      type: object
                      properties:
                        fileId:
                          type: number
                        listingName:
                          type: string
                        offersCount:
                          type: number
                        latestOfferDate:
                          type: ISO Date
                        hasNewOffers:
                          type: boolean
                        viewOffersLink:
                          type: string
              example:
                hasNewOffers: true
                listings:
                - fileId: 12345
                  listingName: property X
                  offersCount: 3
                  hasNewOffers: true
                  latestOfferDate: '2023-06-27T14:58:25.439Z'
                  viewOffersLink: https://offers.skyslope.com/file/12345
                - fileId: 67890
                  listingName: property Y
                  offersCount: 4
                  hasNewOffers: false
                  latestOfferDate: '2022-06-27T14:58:25.439Z'
                  viewOffersLink: https://offers.skyslope.com/file/67890
        '204':
          description: No Content
        '400':
          description: Bad Request - Missing or invalid request parameters
        '401':
          description: Unauthorized - Missing or invalid API key
        '500':
          description: Internal Server Error