Files

The File object represents an uploaded file stored in the EstatePrime system. Files can be linked to a contact, a listing, or placed inside a folder. This object is returned in JSON format.

Object

File object

{
  "id": 204,
  "file_name": "sale_agreement_draft.pdf",
  "url": "https://files.example.com/files/contacts/45/sale_agreement_draft.pdf",
  "size": 204800,
  "date_created": "2025-03-10 11:30:00",
  "user_id": 3,
  "contact_id": 45,
  "listing_id": null,
  "folder_id": 7
}

• id (int): The system id of the file.
• file_name (string): The display name of the file.
• url (string): The full URL to download the file.
• size (int): The file size in bytes.
• date_created (string): The date and time the file was uploaded in YYYY-MM-DD HH:MM:SS format.
• user_id (int): The user ID of the user who uploaded the file.
• contact_id (int, nullable): The ID of the linked contact, or null if not linked to a contact.
• listing_id (int, nullable): The ID of the linked listing, or null if not linked to a listing.
• folder_id (int, nullable): The ID of the folder this file is in, or null if not in a folder.

Folder object

{
  "id": 7,
  "name": "Contracts",
  "parent_id": null,
  "contact_id": 45,
  "listing_id": null
}

• id (int): The system id of the folder.
• name (string): The display name of the folder.
• parent_id (int, nullable): The ID of the parent folder, or null if this is a top-level folder.
• contact_id (int, nullable): The ID of the contact this folder belongs to, or null if not contact-specific.
• listing_id (int, nullable): The ID of the listing this folder belongs to, or null if not listing-specific.

Get files

/api/files (GET)

Fetch a paginated list of files.

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.
  • name (string): Filter by file name (partial match).
  • contact_id (int): Filter files belonging to a single contact.
  • contact_ids (array of int): Filter files belonging to any of the given contact IDs. Ignored if contact_id is provided.
  • listing_id (int): Filter files belonging to a single listing.
  • listing_ids (array of int): Filter files belonging to any of the given listing IDs. Ignored if listing_id is provided.
  • user_id (int): Filter by the user who uploaded the files.
  • folder_id (int): Filter files inside a specific folder.
  • date_created (object): Filter by upload 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.
  • size (object): Filter by file size range in bytes. Must include:
    • min (int): The minimum size in bytes, or null for no lower limit.
    • max (int): The maximum size in bytes, or null for no upper limit.

Example Body

{
  "page": 1,
  "contact_id": 45,
  "date_created": {
    "min": "2025-01-01 00:00:00",
    "max": null
  },
  "size": {
    "min": null,
    "max": 5242880
  }
}

Response

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

Example Response

{
  "status": 200,
  "page": 1,
  "total_pages": 2,
  "results_per_page": 50,
  "total_results": 63,
  "data": [
    {
      "id": 204,
      "file_name": "sale_agreement_draft.pdf",
      "url": "https://files.example.com/files/contacts/45/sale_agreement_draft.pdf",
      "size": 204800,
      "date_created": "2025-03-10 11:30:00",
      "user_id": 3,
      "contact_id": 45,
      "listing_id": null,
      "folder_id": 7
    }
    //Rest of the data...
  ]
}

Get folders

/api/files/folders (GET)

Fetch a flat list of all active folders.

Request

• Method: GET
• Headers: Include authentication headers.

Response

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

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 3,
      "name": "Buyer Documents",
      "parent_id": null,
      "contact_id": 23,
      "listing_id": null
    },
    {
      "id": 7,
      "name": "Contracts",
      "parent_id": null,
      "contact_id": 45,
      "listing_id": null
    },
    {
      "id": 12,
      "name": "Photos",
      "parent_id": null,
      "contact_id": null,
      "listing_id": 120
    }
  ]
}

Get single folder

/api/files/folders/{id} (GET)

Get a single folder by its id.

Request

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

Example Response

{
  "status": 200,
  "data": {
    "id": 7,
    "name": "Contracts",
    "parent_id": null,
    "contact_id": 45,
    "listing_id": null
  }
}

Response

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