{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c1b1953c-b58d-4ca3-975a-f8f534d3f73e","name":"FeedAPI Documentation","description":"# Getting started\n\nFeed API enables registered data providers to publish real estate listings in realtime on the realestate.co.nz (RE) listings platform. It also enables you to update/retrieve all your listings.  \nOur APIs have been designed around [JSONAPI.org](http://jsonapi.org/) specification.\n\nThis documentation site is also built on the Postman platform, therefore there is an accompanying Postman Collection you can use to test the endpoints. You will see a \"Run in Postman\" button at the top right of this site to make use of this feature.\n\n# How to get access to FeedAPI\n\n- **I’m an existing data provider** - Contact our Platform support team at [platform@realestate.co.nz](https://mailto:platform@realestate.co.nz) with your current details. You will be provided with the details to access our sandbox test environment and set you up on our Slack Data Provider support channel if you don't have it already.\n    \n- **I'm a new data provider** - If you want to signup to be a new data provider, please contact [platform@realestate.co.nz](https://mailto:platform@realestate.co.nz) with your details. Include details about the office or offices you are working with. We will then start the onboarding process of getting you set up and linked in our system. This will include access to our Sandbox environment and Slack support channel.\n    \n\n# Authentication and Authorisation\n\nOnly registered data providers for realestate.co.nz registered agents are given access to this API.  \nAll requests to API endpoints are authenticated and authorised via a Bearer Token as provided in an Authorization header. `Authorization: Bearer`  \nTo request access please contact our Platform support team at [platform@realestate.co.nz](https://mailto:platform@realestate.co.nz).\n\n# Legacy EDI migration\n\nTo make the API more semantically readable, modern fields with string values have been created to replace many legacy EDI fields in the specification. Where possible we have highlighted the legacy field equivalent in the field descriptions.\n\n# Supported status codes\n\nThe Feed API supports as much as possible standard HTTP status codes for request responses. Following are the list of codes currently supported.\n\n- 200 - OK The request has succeeded.\n    \n- 201 - Created The request has succeeded and a new resource has been created as a result of it\n    \n- 202 - Accepted The request has been received and is in process\n    \n- 400 - Bad Request Server could not understand the request\n    \n- 401 - Unauthorized\n    \n- 404 - The requested resource was not found. Note there are occasions where we will return this error for certain resources that do exist by the requester isn't authorised to receive it.\n    \n- 500 - There was a server error on our end\n    \n\n# Supported HTTP Methods\n\nGET POST PUT PATCH\n\n# Accepted Content Types\n\nThe [JSONAPI.org](http://jsonapi.org/) specification dictates that we should support just one content type. `Content-Type: application/vnd.api+json`. However our implementation only supports the more common `Content-Type: application/json`.\n\n# Using the API\n\nThere are three list endpoints, `/suburbs`, `/listing-property-types` and `/products` which are provided as reference lists to populate other fields, specifically with regards to listings. The data returned from these endpoints is subject to change, therefore it is important to check these endpoints to ensure you are providing the latest data to your customers.\n\nThe top level resource endpoints like `/listings` and `/agents` provide filters to reduced the list of objects within scope of the request. The format of the request's GET parameters should will look like `/listings?fields[agentId]=235234&filters[listing-status]=active`. This example will return only those listings that are active and listings by the agent represented by the ID 235234.  \nThis resource endpoints also support pagination through the page filters. The request `/listings?page=[limit]=20&page[offset]=100` will return page 6 of listings.\n\n# Workflow for creating a listing\n\nCreating a listing with all the linked related resources like photos and openhomes can take a number of calls. The suggested best practice is:\n\n1. POST the new listing details to create the new record. Record on your side the new Listing ID in the responses.\n    \n2. Using the new listing ID. POST the images to be linked to the listing. These can be done asyncronously once the listing has been created.\n    \n3. Add the relevant open homes.\n    \n4. Place the promotional bookings for the listing.\n    \n5. Once live you can call at a frequency that suits the listing reporting and enquiries endpoints to present to your customer the data around listing engagement on realestate.co.nz\n    \n\n# Error management\n\nThere is a very long list of why a resource may not succeed when trying create or update it. Typically, these are due to a validation error of some kind. We strive to provide logical error messages in the API call response body. Please ensure you pass onto your customers the errors as they happen to best enable them to rectify the issue in your software promptly.\n\n# Support\n\nOur Platform support team are available via email ([platform@realstate.co.nz](https://mailto:platform@realstate.co.nz)) or Slack. Contact via email if your company doesn't have a support Slack channel yet.\n\n# Going live with the API\n\nWhen you believe you are ready to go live, contact Platform support and we can help you validate your integration and then work with you on setting up the tokens and access to our production environment.\n\n# FAQ\n\n- Is there a Sandbox website I can visit to see the result of what I send through?  \n    No, we do not currently offer a GUI for sandbox. Developers typically call the appropriate GET endpoint after sending through data to validate its successful creation.\n    \n- There is lot of metadata and realestate.co.nz specific notations for standard objects like address and suburbs which could be different from other providers. Can it be simplified or use standard data?  \n    We are constantly looking to improve the process for everyone, especially for the end users who the listings are advertised to. If you have any suggestions please contact Platform support through your dedicated Slack channel or on [platform@realestate.co.nz](https://mailto:platform@realestate.co.nz).\n    \n- How do I reactivate a withdrawn listing?  \n    If the listing was withdrawn within the last 30 days, you must send a PATCH request to change the status back to `active`.  \n    For listings that were withdrawn longer than 30 days ago, send a POST request to create a new listing.\n    \n\nContact Support:  \nName: realestate.co.nz platform  \nEmail: [platform@realestate.co.nz](https://mailto:platform@realestate.co.nz)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"424915","team":1451920,"collectionId":"c1b1953c-b58d-4ca3-975a-f8f534d3f73e","publishedId":"T1Dv6ZEp","public":true,"publicUrl":"https://feedapi.developers.realestate.co.nz","privateUrl":"https://go.postman.co/documentation/424915-c1b1953c-b58d-4ca3-975a-f8f534d3f73e","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"00B5E2"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2020-11-24T01:37:21.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Sandbox","id":"91715aa0-789a-4b0a-b7b0-5628893224ec","owner":"424915","values":[{"key":"feed-api.hostname","value":"https://sandbox.realestate.co.nz/feed/v1","enabled":true},{"key":"feed_auth_token","value":"42cc0fccf95b07fb56f61ca68e3b3990","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://realestate.co.nz/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Sandbox","value":"424915-91715aa0-789a-4b0a-b7b0-5628893224ec"}],"canonicalUrl":"https://feedapi.developers.realestate.co.nz/view/metadata/T1Dv6ZEp"}