Settld API Documentation (1.3.0)

Download OpenAPI specification:

Introduction

Settld’s REST API is a service that allows third parties to integrate with Settld’s platform.

Concepts

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.

  • The 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.
  • Use the id from a list or create response for GET, PUT and DELETE on /buyers/{buyerUUID}.
  • Withdrawing a record (DELETE) cancels that one sale. The purchaser, the property and any other sales for the same purchaser are unaffected.
  • Re-sending the same payload to 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.

Environment

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

Authentication

In order to use the API, the consumer will be provided with an API Key, DeveloperUUID and ProjectUUID in the request header

apiKey

Security Scheme Type: API Key
Header parameter name: x-api-key

DeveloperUUID

Security Scheme Type: API Key
Header parameter name: DeveloperUUID

ProjectUUID

Security Scheme Type: API Key
Header parameter name: ProjectUUID

All buyers

Fetch all buyer records for the project

Returns every active buyer record (one purchaser on one property) for the project identified by the ProjectUUID header. Withdrawn sales are excluded.

Authorizations:
(apiKeyDeveloperUUIDProjectUUID)

Responses

Response Schema: application/json
Array of objects

Array of buyers

Array
id
string

Unique identifier of this buyer record - one purchaser on one property, i.e. one sale. Use it for GET, PUT and DELETE.

object
stage
integer

Property stage number

stageDisplay
string

Stage name as shown in Settld; falls back to the stage number. Read-only.

floor
integer

Floor number

floorLabel
string or null

Floor as displayed in Settld. Read-only.

doorNumber
string

Door number of the property

building
string or null

Building identifier. Used with stage and door number for property uniqueness.

unitType
string

Unit type (e.g., 2B for 2 bedrooms)

lot
string

Lot number

designAmendments
string or null

Construction / design variations for the property, free text. Shown as Design Amendments in Settld.

object
firstName
string

Purchaser given name.

familyName
string

Purchaser family name.

mobile
string or null

Purchaser mobile number, or null when none has been supplied.

mobileCountry
string

Uppercase ISO 3166-1 alpha-2 country code of the mobile number (e.g. AU, NZ, GB). Optional; defaults to AU when omitted on create. Existing buyers keep their country unless a new one is supplied.

email
string

Purchaser email. This is the de-duplication key: a payload with an email already in the project updates that purchaser instead of creating a new one.

address
string

Purchaser postal address.

buyerType
string
Enum: "Pending" "Investor" "Owner Occupier" "First Home Buyer" "Upsizer" "Downsizer"

Purchaser category used in reporting.

isPrimary
boolean

True for the primary purchaser of the unit. Co-purchasers share the unit with their own record and id.

object
purchasePrice
string <decimal>

Purchase price as decimal - format: 1500000.00

depositAmount
string or null

Deposit paid, in AUD, as a decimal string; null when not recorded.

depositType
string or null
Enum: "Cash" "Deposit Bond" "Coposit" null

How the deposit was provided; null when not recorded.

dateOfExchange
string <date>

Date of exchange in YYYY-MM-DD format

settlementNoticePeriodDays
integer

Settlement notice period in days

colourSchemeSelection
string

Selected colour scheme

variations
string or null

Contract variations for this sale, free text.

object
intSqm
string <decimal>

Internal square meters as decimal - format: 82.00

extSqm
string <decimal>

External square meters as decimal - format: 10.00

carBays
integer

Number of car bays

object
required
boolean
object
agency
string

Selling agency name.

name
string

Selling agent full name.

email
string

Selling agent email.

phone
string

Selling agent phone.

object
firm
string

Purchaser's solicitor or conveyancer firm.

name
string

Purchaser's solicitor contact name.

email
string

Purchaser's solicitor email.

phone
string

Purchaser's solicitor phone.

object
createdAt
string <date-time>

Timestamp when the buyer record was created (ISO 8601 format)

updatedAt
string <date-time>

Timestamp when the buyer record was last updated (ISO 8601 format)

Response samples

Content type
application/json
{
  • "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)

Create new buyer(s) for the specified project

Create new buyer(s) for the specified project. Buyers are expected to be an array of objects.

How we prevent data duplication

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.

Authorizations:
(apiKeyDeveloperUUIDProjectUUID)
Request Body schema: application/json
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
required
object
stage
integer >= 1

Property stage number (must exist in project completion dates)

floor
integer >= 1

Floor number

doorNumber
required
string

Door number of the property

building
string or null

Building identifier. Used with stage and door number for property uniqueness.

unitType
string

Unit type (e.g., 2B for 2 bedrooms)

lot
string

Lot number

designAmendments
string

Construction / design variations for the property, free text of any length. Shown as Design Amendments in Settld.

required
object
firstName
required
string

Purchaser given name.

familyName
required
string

Purchaser family name.

mobile
string

Purchaser mobile number, used for SMS notifications and SMS login codes. Optional: omit it or send null when the purchaser has no mobile - login codes are emailed and the purchaser can add a mobile in the Settld app. On update, null leaves the stored number unchanged (the API reads null as "leave unchanged"); send the real number with a PUT once you have it.

mobileCountry
string

Uppercase ISO 3166-1 alpha-2 country code of the mobile number (e.g. AU, NZ, GB). Optional; defaults to AU when omitted on create. Existing buyers keep their country unless a new one is supplied.

email
required
string

Purchaser email. This is the de-duplication key: a payload with an email already in the project updates that purchaser instead of creating a new one.

address
string

Purchaser postal address.

buyerType
string
Enum: "Pending" "Investor" "Owner Occupier" "First Home Buyer" "Upsizer" "Downsizer"

Purchaser category used in reporting.

isPrimary
boolean

Set true to make this purchaser the primary purchaser of the unit; any other purchaser on the same unit is demoted. Omit or false to leave the existing primary in place - a unit always keeps exactly one primary. Rejected with 422 for a resold sale.

object
purchasePrice
number

Purchase price in AUD, e.g. 780000.00. A numeric string is also accepted.

depositAmount
number

Deposit paid, in AUD. Optional. A numeric string is also accepted.

depositType
string
Enum: "Cash" "Deposit Bond" "Coposit"

How the deposit was provided. Optional.

dateOfExchange
string <date>

Date of exchange in YYYY-MM-DD format

settlementNoticePeriodDays
number

Days of notice the purchaser receives before settlement.

colourSchemeSelection
string

Selected colour scheme

variations
string

Contract variations for this sale, free text of any length.

object
intSqm
number

Internal area in square metres.

extSqm
number

External area (balcony, courtyard) in square metres.

carBays
number

Number of car bays included in the sale.

object

Foreign Investment Review Board status. Optional; defaults to not required.

required
boolean

True if the purchaser needs FIRB approval.

object
agency
string

Selling agency name.

name
string

Selling agent full name.

email
string

Selling agent email.

phone
string

Selling agent phone.

object
firm
string

Purchaser's solicitor or conveyancer firm.

name
string

Purchaser's solicitor contact name.

email
string

Purchaser's solicitor email.

phone
string

Purchaser's solicitor phone.

Responses

Response Schema: application/json
Array of objects
Array
id
string

Unique identifier of this buyer record - one purchaser on one property, i.e. one sale. Use it for GET, PUT and DELETE.

object
stage
integer

Property stage number

stageDisplay
string

Stage name as shown in Settld; falls back to the stage number. Read-only.

floor
integer

Floor number

floorLabel
string or null

Floor as displayed in Settld. Read-only.

doorNumber
string

Door number of the property

building
string or null

Building identifier. Used with stage and door number for property uniqueness.

unitType
string

Unit type (e.g., 2B for 2 bedrooms)

lot
string

Lot number

designAmendments
string or null

Construction / design variations for the property, free text. Shown as Design Amendments in Settld.

object
firstName
string

Purchaser given name.

familyName
string

Purchaser family name.

mobile
string or null

Purchaser mobile number, or null when none has been supplied.

mobileCountry
string

Uppercase ISO 3166-1 alpha-2 country code of the mobile number (e.g. AU, NZ, GB). Optional; defaults to AU when omitted on create. Existing buyers keep their country unless a new one is supplied.

email
string

Purchaser email. This is the de-duplication key: a payload with an email already in the project updates that purchaser instead of creating a new one.

address
string

Purchaser postal address.

buyerType
string
Enum: "Pending" "Investor" "Owner Occupier" "First Home Buyer" "Upsizer" "Downsizer"

Purchaser category used in reporting.

isPrimary
boolean

True for the primary purchaser of the unit. Co-purchasers share the unit with their own record and id.

object
purchasePrice
string <decimal>

Purchase price as decimal - format: 780000.00

depositAmount
string or null

Deposit paid, in AUD, as a decimal string; null when not recorded.

depositType
string or null
Enum: "Cash" "Deposit Bond" "Coposit" null

How the deposit was provided; null when not recorded.

dateOfExchange
string <date>

Date of exchange in YYYY-MM-DD format

settlementNoticePeriodDays
integer

Settlement notice period in days

colourSchemeSelection
string

Selected colour scheme

variations
string or null

Contract variations for this sale, free text.

object
intSqm
string <decimal>

Internal square meters as decimal - format: 78.00

extSqm
string <decimal>

External square meters as decimal - format: 12.00

carBays
integer

Number of car bays

object
required
boolean
object
agency
string

Selling agency name.

name
string

Selling agent full name.

email
string

Selling agent email.

phone
string

Selling agent phone.

object
firm
string

Purchaser's solicitor or conveyancer firm.

name
string

Purchaser's solicitor contact name.

email
string

Purchaser's solicitor email.

phone
string

Purchaser's solicitor phone.

object
createdAt
string <date-time>

Timestamp when the buyer record was created (ISO 8601 format)

updatedAt
string <date-time>

Timestamp when the buyer record was last updated (ISO 8601 format)

Request samples

Content type
application/json
{
  • "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"
        }
      }
    ]
}

Response samples

Content type
application/json
{
  • "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"
        }
      }
    ]
}

Get a buyer

Fetch a single buyer record

Returns the buyer record whose id matches buyerUUID. The id comes from a list or create response.

Authorizations:
(apiKeyDeveloperUUIDProjectUUID)

Responses

Response Schema: application/json
object
id
string

Unique identifier of this buyer record - one purchaser on one property, i.e. one sale. Use it for GET, PUT and DELETE.

object
stage
number

Completion stage sequence number within the project. Defaults to the project's first stage when omitted.

stageDisplay
string

Stage name as shown in Settld; falls back to the stage number. Read-only.

floor
integer

Floor number

floorLabel
string or null

Floor as displayed in Settld. Read-only.

doorNumber
string

Door number of the property

building
string or null

Building identifier. Used with stage and door number for property uniqueness.

unitType
string

Unit type code, e.g. 2B2B.

lot
string

Lot number

designAmendments
string or null

Construction / design variations for the property, free text. Shown as Design Amendments in Settld.

object
firstName
string

Purchaser given name.

familyName
string

Purchaser family name.

mobile
string or null

Purchaser mobile number, or null when none has been supplied.

mobileCountry
string

Uppercase ISO 3166-1 alpha-2 country code of the mobile number (e.g. AU, NZ, GB). Optional; defaults to AU when omitted on create. Existing buyers keep their country unless a new one is supplied.

email
string

Purchaser email. This is the de-duplication key: a payload with an email already in the project updates that purchaser instead of creating a new one.

address
string

Purchaser postal address.

buyerType
string
Enum: "Pending" "Investor" "Owner Occupier" "First Home Buyer" "Upsizer" "Downsizer"

Purchaser category used in reporting.

isPrimary
boolean

True for the primary purchaser of the unit. Co-purchasers share the unit with their own record and id.

object
purchasePrice
string <decimal>

Purchase price as decimal - format: 1500000.00

depositAmount
string or null

Deposit paid, in AUD, as a decimal string; null when not recorded.

depositType
string or null
Enum: "Cash" "Deposit Bond" "Coposit" null

How the deposit was provided; null when not recorded.

dateOfExchange
string <date>

Date of exchange in YYYY-MM-DD format

settlementNoticePeriodDays
number
colourSchemeSelection
string

Selected colour scheme

variations
string or null

Contract variations for this sale, free text.

object
intSqm
string <decimal>

Internal square meters as decimal - format: 82.00

extSqm
string <decimal>

External square meters as decimal - format: 10.00

carBays
number
object
required
boolean
object
agency
string

Selling agency name.

name
string

Selling agent full name.

email
string

Selling agent email.

phone
string

Selling agent phone.

object
firm
string

Purchaser's solicitor or conveyancer firm.

name
string

Purchaser's solicitor contact name.

email
string

Purchaser's solicitor email.

phone
string

Purchaser's solicitor phone.

object
createdAt
string <date-time>

Timestamp when the buyer record was created (ISO 8601 format)

updatedAt
string <date-time>

Timestamp when the buyer record was last updated (ISO 8601 format)

Response samples

Content type
application/json
{
  • "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"
      }
    }
}

Update buyer

Update a buyer record

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.

Authorizations:
(apiKeyDeveloperUUIDProjectUUID)
Request Body schema: application/json
object
stage
integer >= 1

Property stage number (must exist in project completion dates)

floor
integer >= 1

Floor number

doorNumber
required
string

Door number of the property

building
string or null

Building identifier. Used with stage and door number for property uniqueness.

unitType
string

Unit type (e.g., 2B for 2 bedrooms)

lot
string

Lot number

designAmendments
string

Construction / design variations for the property, free text of any length. Shown as Design Amendments in Settld.

object
firstName
required
string

Purchaser given name.

familyName
required
string

Purchaser family name.

mobile
string

Purchaser mobile number, used for SMS notifications and SMS login codes. Optional: omit it or send null when the purchaser has no mobile - login codes are emailed and the purchaser can add a mobile in the Settld app. On update, null leaves the stored number unchanged (the API reads null as "leave unchanged"); send the real number with a PUT once you have it.

mobileCountry
string

Uppercase ISO 3166-1 alpha-2 country code of the mobile number (e.g. AU, NZ, GB). Optional; defaults to AU when omitted on create. Existing buyers keep their country unless a new one is supplied.

email
required
string

Purchaser email. This is the de-duplication key: a payload with an email already in the project updates that purchaser instead of creating a new one.

address
string

Purchaser postal address.

buyerType
string
Enum: "Pending" "Investor" "Owner Occupier" "First Home Buyer" "Upsizer" "Downsizer"

Purchaser category used in reporting.

isPrimary
boolean

Set true to make this purchaser the primary purchaser of the unit; any other purchaser on the same unit is demoted. Omit or false to leave the existing primary in place - a unit always keeps exactly one primary. Rejected with 422 for a resold sale.

object
purchasePrice
number

Purchase price in AUD, e.g. 780000.00. A numeric string is also accepted.

depositAmount
number

Deposit paid, in AUD. Optional. A numeric string is also accepted.

depositType
string
Enum: "Cash" "Deposit Bond" "Coposit"

How the deposit was provided. Optional.

dateOfExchange
string <date>

Date of exchange in YYYY-MM-DD format

settlementNoticePeriodDays
number

Days of notice the purchaser receives before settlement.

colourSchemeSelection
string

Selected colour scheme

variations
string

Contract variations for this sale, free text of any length.

object
intSqm
number

Internal area in square metres.

extSqm
number

External area (balcony, courtyard) in square metres.

carBays
number

Number of car bays included in the sale.

object

Foreign Investment Review Board status. Optional; defaults to not required.

required
boolean

True if the purchaser needs FIRB approval.

object
agency
string

Selling agency name.

name
string

Selling agent full name.

email
string

Selling agent email.

phone
string

Selling agent phone.

object
firm
string

Purchaser's solicitor or conveyancer firm.

name
string

Purchaser's solicitor contact name.

email
string

Purchaser's solicitor email.

phone
string

Purchaser's solicitor phone.

Responses

Response Schema: application/json
object
id
string

Unique identifier of this buyer record - one purchaser on one property, i.e. one sale. Use it for GET, PUT and DELETE.

object
stage
number

Completion stage sequence number within the project. Defaults to the project's first stage when omitted.

stageDisplay
string

Stage name as shown in Settld; falls back to the stage number. Read-only.

floor
integer

Floor number

floorLabel
string or null

Floor as displayed in Settld. Read-only.

doorNumber
string

Apartment or door number. Together with stage and building this identifies the property for de-duplication.

building
string or null

Building identifier. Used with stage and door number for property uniqueness.

unitType
string

Unit type code, e.g. 2B2B.

lot
string

Lot number on the strata plan.

designAmendments
string or null

Construction / design variations for the property, free text. Shown as Design Amendments in Settld.

object
firstName
string

Purchaser given name.

familyName
string

Purchaser family name.

mobile
string or null

Purchaser mobile number, or null when none has been supplied.

mobileCountry
string

Uppercase ISO 3166-1 alpha-2 country code of the mobile number (e.g. AU, NZ, GB). Optional; defaults to AU when omitted on create. Existing buyers keep their country unless a new one is supplied.

email
string

Purchaser email. This is the de-duplication key: a payload with an email already in the project updates that purchaser instead of creating a new one.

address
string

Purchaser postal address.

buyerType
string
Enum: "Pending" "Investor" "Owner Occupier" "First Home Buyer" "Upsizer" "Downsizer"

Purchaser category used in reporting.

isPrimary
boolean

True for the primary purchaser of the unit. Co-purchasers share the unit with their own record and id.

object
purchasePrice
string
depositAmount
string or null

Deposit paid, in AUD, as a decimal string; null when not recorded.

depositType
string or null
Enum: "Cash" "Deposit Bond" "Coposit" null

How the deposit was provided; null when not recorded.

dateOfExchange
string

Date contracts were exchanged, YYYY-MM-DD. A record without an exchange date is treated as not yet exchanged in reporting.

settlementNoticePeriodDays
number
colourSchemeSelection
string

Colour scheme the purchaser selected, free text.

variations
string or null

Contract variations for this sale, free text.

object
intSqm
number
extSqm
number
carBays
number
object
required
boolean
object
agency
string

Selling agency name.

name
string

Selling agent full name.

email
string

Selling agent email.

phone
string

Selling agent phone.

object
firm
string

Purchaser's solicitor or conveyancer firm.

name
string

Purchaser's solicitor contact name.

email
string

Purchaser's solicitor email.

phone
string

Purchaser's solicitor phone.

object
createdAt
string <date-time>

Timestamp when the buyer record was created (ISO 8601 format)

updatedAt
string <date-time>

Timestamp when the buyer record was last updated (ISO 8601 format)

Request samples

Content type
application/json
{
  • "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"
    }
}

Response samples

Content type
application/json
{
  • "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"
      }
    }
}

Withdraw a sale

Withdraw a sale (cancellation / rescission)

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.

Authorizations:
(apiKeyDeveloperUUIDProjectUUID)

Responses

Response Schema: application/json
message
string

Response samples

Content type
application/json
{
  • "message": "Sale withdrawn"
}

Project engagement summary

Fetch a project's engagement summary

Returns live engagement metrics for the project identified by projectUuid - the same figures shown on the Settld dashboard.

Authorizations:
(apiKeyDeveloperUUIDProjectUUID)

Responses

Response Schema: application/json
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

Response samples

Content type
application/json
{
  • "projectExtId": "f3a9275a-580d-4e96-b1d4-1d021af162ce",
  • "unansweredChats": 3,
  • "purchaserContactsConfirmed": 120,
  • "appRegistrations": 210,
  • "buyersRegistered": 210,
  • "buyersTotal": 350,
  • "settlementRiskPercent": 12,
  • "settlementRiskAmount": 10500000
}