Download OpenAPI specification:
Settld’s REST API is a service that allows third parties to integrate with Settld’s platform.
Every record the Buyers endpoints return is one purchaser on one property, i.e. one sale or contract. It is called a buyer record throughout these docs.
id on a record identifies that sale, not the person. A purchaser who buys two apartments in the project appears as two records with two different ids that share the same buyer block.id from a list or create response for GET, PUT and DELETE on /buyers/{buyerUUID}.DELETE) cancels that one sale. The purchaser, the property and any other sales for the same purchaser are unaffected.POST /buyers is safe: records are matched on purchaser email plus the property's stage, door number and building, and updated rather than duplicated (see How we prevent data duplication).Every request must carry the three headers described under Authentication. All timestamps are ISO-8601 in UTC; dates are YYYY-MM-DD.
The API provides two environments: Production and Staging/Sandbox.
| Name | Environment URL |
|---|---|
| Production | https://api.settld.com.au/v1 |
| Staging/Sandbox | https://api.settld.app/v1 |
In order to use the API, the consumer will be provided with an API Key, DeveloperUUID and ProjectUUID in the request header
Returns every active buyer record (one purchaser on one property) for the project identified by the ProjectUUID header. Withdrawn sales are excluded.
Array of objects Array of buyers | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{- "data": [
- {
- "id": "f72ef452-32a3-49e9-854d-6eef2df8b649",
- "property": {
- "stage": 1,
- "floor": 1,
- "doorNumber": "301",
- "unitType": "2B",
- "lot": "301",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "Claire",
- "familyName": "Martinez",
- "mobile": "0411111111",
- "mobileCountry": "AU",
- "email": "claire.martinez@settld.com.au",
- "address": "111 Test Street, Sydney, 2000 NSW",
- "buyerType": "Pending",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "1500000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-06-11",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Light",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "82.00",
- "extSqm": "10.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Troy Collins",
- "email": "troy@rayw.com.au",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Martin Scorcese",
- "email": "ms@lawyers.com.au",
- "phone": "412222222"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-06-11T06:02:08.000000Z"
}
}, - {
- "id": "2e5929ea-50aa-4a6e-80fe-96dd4d9e24e7",
- "property": {
- "stage": 1,
- "doorNumber": "302",
- "unitType": "2B",
- "lot": "302",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "Kylie",
- "familyName": "Ventura",
- "mobile": "0411111112",
- "mobileCountry": "AU",
- "email": "kylie.ventura@settld.com.au",
- "address": "112 Test Street, Sydney, 2000 NSW",
- "buyerType": "Pending",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "1500000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-06-11",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Light",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "82.00",
- "extSqm": "10.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Troy Collins",
- "email": "troy@rayw.com.au",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Martin Scorcese",
- "email": "ms@lawyers.com.au",
- "phone": "412222222"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-06-11T06:02:08.000000Z"
}
}, - {
- "id": "6b7873d8-a2a0-4d37-817c-5164f6f29680",
- "property": {
- "stage": 1,
- "doorNumber": "303",
- "unitType": "2B",
- "lot": "303",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "Trent",
- "familyName": "Johnson",
- "mobile": "0411111113",
- "mobileCountry": "AU",
- "email": "trent.johnson@settld.com.au",
- "address": "113 Test Street, Sydney, 2000 NSW",
- "buyerType": "Pending",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "1500000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-06-11",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Light",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "82.00",
- "extSqm": "10.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Troy Collins",
- "email": "troy@rayw.com.au",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Martin Scorcese",
- "email": "ms@lawyers.com.au",
- "phone": "412222222"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-06-11T06:02:08.000000Z"
}
}, - {
- "id": "d4c00cb8-d1a5-4f93-ad11-795359ac5c8d",
- "property": {
- "stage": 1,
- "doorNumber": "304",
- "unitType": "2B",
- "lot": "304",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "Samuel",
- "familyName": "Smith",
- "mobile": "0411111114",
- "mobileCountry": "AU",
- "email": "samuel.smith@settld.com.au",
- "address": "114 Test Street, Sydney, 2000 NSW",
- "buyerType": "Pending",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "1500000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-06-11",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Light",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "82.00",
- "extSqm": "10.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Troy Collins",
- "email": "troy@rayw.com.au",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Martin Scorcese",
- "email": "ms@lawyers.com.au",
- "phone": "412222222"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-06-11T06:02:08.000000Z"
}
}, - {
- "id": "3463dc2c-af35-4bea-b0aa-895a62680aac",
- "property": {
- "stage": 1,
- "doorNumber": "305",
- "unitType": "2B",
- "lot": "305",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "Samuel",
- "familyName": "Baskin",
- "mobile": "0411111115",
- "mobileCountry": "AU",
- "email": "leo.baskin@settld.com.au",
- "address": "115 Test Street, Sydney, 2000 NSW",
- "buyerType": "Pending",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "1500000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-06-11",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Light",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "82.00",
- "extSqm": "10.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Troy Collins",
- "email": "troy@rayw.com.au",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Martin Scorcese",
- "email": "ms@lawyers.com.au",
- "phone": "412222222"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-06-11T06:02:08.000000Z"
}
}, - {
- "id": "2b8430a4-f52f-4b29-87c3-bb95b1ebd211",
- "property": {
- "stage": 1,
- "doorNumber": "306",
- "unitType": "2B",
- "lot": "306",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "Eli",
- "familyName": "Patrick",
- "mobile": "0411111116",
- "mobileCountry": "AU",
- "email": "eli.patrick@settld.com.au",
- "address": "116 Test Street, Sydney, 2000 NSW",
- "buyerType": "Pending",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "1500000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-06-11",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Light",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "82.00",
- "extSqm": "10.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Troy Collins",
- "email": "troy@rayw.com.au",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Martin Scorcese",
- "email": "ms@lawyers.com.au",
- "phone": "412222222"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-06-11T06:02:08.000000Z"
}
}
]
}Create new buyer(s) for the specified project. Buyers are expected to be an array of objects.
The system checks the buyer email and the property's stage, door number, and building before creating new records.
If the buyer email already exists, we update and reuse that buyer instead of creating another buyer.
If a property with the same stage, door number, and building already exists in the project, we update and reuse that property instead of creating another property. Empty/null building values match each other for backward compatibility.
If the same buyer email is already linked to the same property stage, door number, and building, we update that existing buyer-property record.
If the buyer email exists and the property stage, door number, and building exist but they are not linked yet, we link the existing buyer to the existing property and create or update the related buyer-property details.
If two different buyers are submitted for the same property stage, door number, and building, each buyer is saved separately, but they share the same property record.
| isExistingBuyerOverrideConfirmed | boolean Default: false A row whose email already belongs to a buyer in the project reuses that buyer record and rewrites their name, mobile, mobile country and address on every unit they hold. Such a row is rejected with a 422 naming the buyer and their units unless this flag is true. A row whose details equal the stored ones only links the unit and needs no flag. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
required | Array of objects Array of buyers to create | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{- "buyers": [
- {
- "property": {
- "stage": 1,
- "floor": 1,
- "doorNumber": "A12",
- "unitType": "2B",
- "lot": "202",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "John",
- "familyName": "Smith",
- "mobile": "0400000000",
- "mobileCountry": "AU",
- "email": "john.smith@example.com",
- "address": "10 Smith St",
- "buyerType": "Owner Occupier",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "780000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-03-01",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Coastal",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": 78,
- "extSqm": 12,
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Alice Cooper",
- "email": "alice@raywhite.com",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Mark Smith",
- "email": "mark@smithlegal.com",
- "phone": "0298765432"
}
}
]
}{- "data": [
- {
- "id": "7799ab46-46a3-4fbf-81d0-69762ecb7b6b",
- "property": {
- "stage": 1,
- "floor": 1,
- "doorNumber": "A12",
- "unitType": "2B",
- "lot": "202",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "John",
- "familyName": "Smith",
- "mobile": "0400000000",
- "mobileCountry": "AU",
- "email": "john.smith@example.com",
- "address": "10 Smith St",
- "buyerType": "Owner Occupier",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "780000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-03-01",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Coastal",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "78.00",
- "extSqm": "12.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Alice Cooper",
- "email": "alice@raywhite.com",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Mark Smith",
- "email": "mark@smithlegal.com",
- "phone": "0298765432"
}, - "metadata": {
- "createdAt": "2025-12-10T10:30:04.000000Z",
- "updatedAt": "2025-12-10T10:30:04.000000Z"
}
}
]
}Returns the buyer record whose id matches buyerUUID. The id comes from a list or create response.
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{- "data": {
- "id": "f72ef452-32a3-49e9-854d-6eef2df8b649",
- "property": {
- "stage": 1,
- "floor": 1,
- "doorNumber": "301",
- "unitType": "2B",
- "lot": "301",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "Claire",
- "familyName": "Martinez",
- "mobile": "0411111111",
- "mobileCountry": "AU",
- "email": "claire.martinez@settld.com.au",
- "address": "111 Test Street, Sydney, 2000 NSW",
- "buyerType": "Pending",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "1500000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-06-11",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Light",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": "82.00",
- "extSqm": "10.00",
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Troy Collins",
- "email": "troy@rayw.com.au",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Martin Scorcese",
- "email": "ms@lawyers.com.au",
- "phone": "412222222"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-06-11T06:02:08.000000Z"
}
}
}Partially updates the buyer record whose id matches buyerUUID. Send only the fields you want to change; every field is optional and omitted fields are left as they are. Changing buyer.email to an address already used by another buyer in the project is rejected with 422 - merge the buyers in Settld instead.
object | |||||||||||||||||
| |||||||||||||||||
object | |||||||||||||||||
| |||||||||||||||||
object | |||||||||||||||||
| |||||||||||||||||
object | |||||||||||||||||
| |||||||||||||||||
object Foreign Investment Review Board status. Optional; defaults to not required. | |||||||||||||||||
| |||||||||||||||||
object | |||||||||||||||||
| |||||||||||||||||
object | |||||||||||||||||
| |||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
{- "property": {
- "stage": 1,
- "floor": 1,
- "doorNumber": "A12",
- "unitType": "2B",
- "lot": "202",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "John",
- "familyName": "Smith",
- "mobile": "0400000000",
- "mobileCountry": "AU",
- "email": "john.smith@example.com",
- "address": "10 Smith St",
- "buyerType": "Owner Occupier",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "780000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-03-01",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Coastal",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": 78,
- "extSqm": 12,
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Alice Cooper",
- "email": "alice@raywhite.com",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Mark Smith",
- "email": "mark@smithlegal.com",
- "phone": "0298765432"
}
}{- "data": {
- "id": "f72ef452-32a3-49e9-854d-6eef2df8b649",
- "property": {
- "stage": 1,
- "floor": 1,
- "doorNumber": "A12",
- "unitType": "2B",
- "lot": "202",
- "designAmendments": "Kitchen island relocated 300mm east."
}, - "buyer": {
- "firstName": "John",
- "familyName": "Smith",
- "mobile": "0400000000",
- "mobileCountry": "AU",
- "email": "john.smith@example.com",
- "address": "10 Smith St",
- "buyerType": "Owner Occupier",
- "isPrimary": true
}, - "contract": {
- "purchasePrice": "780000.00",
- "depositAmount": "78000.00",
- "depositType": "Cash",
- "dateOfExchange": "2025-03-01",
- "settlementNoticePeriodDays": 21,
- "colourSchemeSelection": "Coastal",
- "variations": "Special condition 14: settlement extended by 21 days."
}, - "dimensions": {
- "intSqm": 78,
- "extSqm": 12,
- "carBays": 1
}, - "firb": {
- "required": true
}, - "sellingAgent": {
- "agency": "Ray White",
- "name": "Alice Cooper",
- "email": "alice@raywhite.com",
- "phone": "0401234567"
}, - "buyerSolicitor": {
- "firm": "Smith Legal",
- "name": "Mark Smith",
- "email": "mark@smithlegal.com",
- "phone": "0298765432"
}, - "metadata": {
- "createdAt": "2025-06-11T06:02:08.000000Z",
- "updatedAt": "2025-12-10T11:05:00.000000Z"
}
}
}Withdraws the sale identified by the buyerUUID, for example when a sale falls through or is rescinded. The sale record is removed from all feeds and reporting, the purchaser's app access for the property is revoked, and the lot automatically reverts to available inventory, ready for a new sale. Withdrawn sales are retained internally for audit purposes. Send the cancellation as part of your sync so no manual step is needed.
| message | string |
{- "message": "Sale withdrawn"
}Returns live engagement metrics for the project identified by projectUuid - the same figures shown on the Settld dashboard.
| projectExtId | string Unique identifier for the project |
| unansweredChats | integer Buyer chat conversations awaiting a reply |
| purchaserContactsConfirmed | integer Purchasers whose contact details are confirmed |
| appRegistrations | integer Buyer app registrations for the project |
| buyersRegistered | integer Buyers registered on the app |
| buyersTotal | integer Total exchanged buyers in the project |
| settlementRiskPercent | integer Share of buyers flagged high settlement risk, percent |
| settlementRiskAmount | number Total purchase value flagged high settlement risk |
{- "projectExtId": "f3a9275a-580d-4e96-b1d4-1d021af162ce",
- "unansweredChats": 3,
- "purchaserContactsConfirmed": 120,
- "appRegistrations": 210,
- "buyersRegistered": 210,
- "buyersTotal": 350,
- "settlementRiskPercent": 12,
- "settlementRiskAmount": 10500000
}