Contracts

The Contract object represents a property sale or rental contract in the EstatePrime system. This object is returned in JSON format, containing all available values for a contract.

Object

The Contract object represents an individual contract record. Below are the fields included in a Contract object:

Example

{
  "id": 17,
  "offer_id": 54,
  "request_id": 31,
  "store_id": 2,
  "status_id": 1,
  "created_by": 3,
  "date_created": "2025-02-18 09:30:00",
  "date_updated": "2025-03-01 11:00:00",
  "status_date": "2025-03-01 11:00:00",
  "currency": "EUR",
  "loan_percentage": 0,
  "initial_property_price": 280000,
  "final_property_price": 265000,
  "deposit_amount": 10000,
  "deposit_date": "2025-02-20",
  "notary_contact_id": 88,
  "notes": "Signed at Thessaloniki notary office.",
  "external_contact": false,
  "listing": {
    "external": false,
    "listing_id": 120
  },
  "contacts": [23, 45]
}

When the contract's listing is an external (off-system) property, the listing object has the following shape instead:

"listing": {
  "external": true,
  "address": "Tsimiski 15, Thessaloniki",
  "price": 240000,
  "owner_name": "George Papadopoulos",
  "listing_code": "EXT-00451",
  "availability": "sale",
  "category": "residential",
  "subcategory": "apartment",
  "size": "95.00",
  "area_level1": 5,
  "area_level2": 12,
  "area_level3": null,
  "listing_link": "https://example.com/listing/451",
  "notes": null
}

• id (int): The system id of the contract.
• offer_id (int): The ID of the offer that led to this contract.
• request_id (int, nullable): The ID of the linked buyer request, or null if not linked.
• store_id (int): The ID of the office/store that owns this contract.
• status_id (int): The ID of the contract status.
• created_by (int): The user ID of the user who created the contract.
• date_created (string): The date and time the contract was created in YYYY-MM-DD HH:MM:SS format.
• date_updated (string): The date and time the contract was last updated in YYYY-MM-DD HH:MM:SS format.
• status_date (string, nullable): The date and time the status was last changed, or null if never changed.
• currency (string): The currency code (e.g., EUR).
• loan_percentage (int): The loan percentage for the transaction (0 if no loan).
• initial_property_price (int, nullable): The initial asking price of the property.
• final_property_price (int, nullable): The agreed final sale/rent price.
• deposit_amount (int, nullable): The deposit amount paid.
• deposit_date (string, nullable): The deposit payment date in YYYY-MM-DD format, or null if not applicable.
• notary_contact_id (int, nullable): The contact ID of the notary, or null if not assigned.
• notes (string, nullable): Optional notes about the contract.
• external_contact (boolean): Indicates if the buyer/interested party is outside the system (not a stored contact).
• listing (object): Information about the property. Contains one of two shapes:
  • When external is false: { "external": false, "listing_id": 120 } — refers to an internal listing.
  • When external is true: Contains the full snapshot of the off-system property. Fields include:
    • address (string, nullable): The property address.
    • price (int, nullable): The asking price.
    • owner_name (string, nullable): The property owner's name.
    • listing_code (string, nullable): An external reference code.
    • availability (string, nullable): Possible values: sale, rent, auction, shortterm.
    • category (string, nullable): Possible values: residential, commercial, land, other.
    • subcategory (string, nullable): The property subcategory.
    • size (decimal, nullable): The property size in square meters.
    • area_level1 (int, nullable): Region ID.
    • area_level2 (int, nullable): Municipality/district ID.
    • area_level3 (int, nullable): Neighbourhood ID.
    • listing_link (string, nullable): A URL link to the external listing.
    • notes (string, nullable): Notes about the external property.
• contacts (array of integers): A list of contact IDs (the interested parties) associated with the contract.

Get contracts

/api/contracts (GET)

Fetch a paginated list of contracts.

Request

• Method: GET
• Headers: Include authentication headers as described in the Authentication section.
• Body: JSON object with the following optional parameters:
  • page (int): The page number to fetch. Defaults to 1.
  • status_id (int): Filter by contract status ID.
  • store_id (int): Filter by office/store ID.
  • offer_id (int): Filter by linked offer ID.
  • listing_id (int): Filter by internal listing ID.
  • request_id (int): Filter by linked buyer request ID.
  • contact_id (int): Filter by associated contact ID.
  • external_listing (boolean): Filter by whether the property is external (true or false).
  • external_contact (boolean): Filter by whether the contact is external (true or false).
  • date_created (object): Filter by creation date range. Must include:
    • min (string): The minimum date in YYYY-MM-DD HH:MM:SS format, or null for no lower limit.
    • max (string): The maximum date in YYYY-MM-DD HH:MM:SS format, or null for no upper limit.
  • status_date (object): Filter by status change date range. Must include:
    • min (string): The minimum date in YYYY-MM-DD HH:MM:SS format, or null for no lower limit.
    • max (string): The maximum date in YYYY-MM-DD HH:MM:SS format, or null for no upper limit.

Example Body

{
  "page": 1,
  "status_id": 1,
  "store_id": 2,
  "date_created": {
    "min": "2025-01-01 00:00:00",
    "max": null
  }
}

Response

• 200 OK: Returns a JSON array of contract objects.

Example Response

{
  "status": 200,
  "page": 1,
  "total_pages": 2,
  "results_per_page": 50,
  "total_results": 63,
  "data": [
    {
      "id": 17,
      "offer_id": 54,
      "request_id": 31,
      "store_id": 2,
      "status_id": 1,
      "created_by": 3,
      "date_created": "2025-02-18 09:30:00",
      "date_updated": "2025-03-01 11:00:00",
      "status_date": "2025-03-01 11:00:00",
      "currency": "EUR",
      "loan_percentage": 0,
      "initial_property_price": 280000,
      "final_property_price": 265000,
      "deposit_amount": 10000,
      "deposit_date": "2025-02-20",
      "notary_contact_id": 88,
      "external_contact": false,
      "listing": {
        "external": false,
        "listing_id": 120
      },
      "contacts": [23, 45]
    }
    //Rest of the data...
  ]
}

Get single contract

/api/contracts/{id} (GET)

Get a single contract by its id.

Request

• Method: GET
• Headers: Include authentication headers.
• Path Params: The contract id to be fetched.

Example Response

{
  "status": 200,
  "data": {
    "id": 17,
    "offer_id": 54,
    "request_id": 31,
    "store_id": 2,
    "status_id": 1,
    "created_by": 3,
    "date_created": "2025-02-18 09:30:00",
    "date_updated": "2025-03-01 11:00:00",
    "status_date": "2025-03-01 11:00:00",
    "currency": "EUR",
    "loan_percentage": 0,
    "initial_property_price": 280000,
    "final_property_price": 265000,
    "deposit_amount": 10000,
    "deposit_date": "2025-02-20",
    "notary_contact_id": 88,
    "notes": "Signed at Thessaloniki notary office.",
    "external_contact": false,
    "listing": {
      "external": false,
      "listing_id": 120
    },
    "contacts": [23, 45]
  }
}

Response

• 200 OK: Returns the JSON object of the contract.

Get contract statuses

/api/contracts/statuses (GET)

Fetch the available contract statuses.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of available contract statuses.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "In Progress",
      "is_completed": false,
      "is_cancelled": false,
      "bg_color": "#467fcf",
      "text_color": "#ffffff"
    },
    {
      "id": 2,
      "name": "Completed",
      "is_completed": true,
      "is_cancelled": false,
      "bg_color": "#09ad95",
      "text_color": "#ffffff"
    },
    {
      "id": 3,
      "name": "Cancelled",
      "is_completed": false,
      "is_cancelled": true,
      "bg_color": "#dc0441",
      "text_color": "#ffffff"
    }
  ]
}

• id (int): The system id of the status.
• name (string): The display name of the status.
• is_completed (boolean): Indicates if this status represents a completed contract.
• is_cancelled (boolean): Indicates if this status represents a cancelled contract.
• bg_color (string): The hex background color used to display the status badge.
• text_color (string): The hex text color used to display the status badge.