Incomes

The Income object represents a financial income record in the EstatePrime system. This object is returned in JSON format, containing all available values for an income entry.

Object

The Income object represents an individual income record. Below are the fields included in an Income object:

Example

{
  "id": 42,
  "category": "contract",
  "other_category_id": null,
  "contract_id": 17,
  "owner_side_amount": "3500.00",
  "client_side_amount": "2000.00",
  "total_amount": "5500.00",
  "date": "2025-03-10",
  "title": null,
  "notes": "Commission from property sale",
  "status": "confirmed",
  "created_by": 3,
  "date_created": "2025-03-10 14:22:00",
  "date_updated": null,
  "commissions": [
    {
      "id": 5,
      "side": "owner_side",
      "partner_id": 8,
      "side_total_commission": "3500.00",
      "partner_commission_amount": "1000.00"
    }
  ],
  "contacts": [23, 45]
}

• id (int): The system id of the income.
• category (string): The income category. Possible values: contract, valuation, referral, other.
• other_category_id (int, nullable): The ID of the custom "other" subcategory, populated when category is other.
• contract_id (int, nullable): The ID of the linked contract, populated when category is contract.
• owner_side_amount (decimal, nullable): The commission amount charged to the property owner's side.
• client_side_amount (decimal, nullable): The commission amount charged to the buyer's side.
• total_amount (decimal): The total income amount.
• date (string): The income date in YYYY-MM-DD format.
• title (string, nullable): An optional title for the income record.
• notes (string, nullable): Optional notes.
• status (string): The income status. Possible values: pending, confirmed.
• created_by (int): The user ID of the user who created the record.
• date_created (string): The date and time the record was created in YYYY-MM-DD HH:MM:SS format.
• date_updated (string, nullable): The date and time the record was last updated, or null if never updated.
• commissions (array of objects): A list of partner commission splits. Each object includes:
  • id (int): The system id of the commission entry.
  • side (string): The side this commission belongs to. Possible values: owner_side, client_side.
  • partner_id (int): The user ID of the partner receiving the commission.
  • side_total_commission (decimal): The total commission amount for this side.
  • partner_commission_amount (decimal): The amount allocated to this specific partner.
• contacts (array of integers): A list of contact IDs associated with the income.

Get incomes

/api/incomes (GET)

Fetch a paginated list of incomes.

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.
  • category (string): Filter by category. Possible values: contract, valuation, referral, other.
  • status (string): Filter by status. Possible values: pending, confirmed.
  • contract_id (int): Filter by linked contract ID.
  • contact_id (int): Filter by associated contact ID.
  • date (object): Filter by income date range. Must include:
    • min (string): The minimum date in YYYY-MM-DD format, or null for no lower limit.
    • max (string): The maximum date in YYYY-MM-DD format, or null for no upper limit.
  • 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.
  • total_amount (object): Filter by total amount range. Must include:
    • min (decimal): The minimum total amount, or null for no lower limit.
    • max (decimal): The maximum total amount, or null for no upper limit.

Example Body

{
  "page": 1,
  "category": "contract",
  "status": "confirmed",
  "date": {
    "min": "2025-01-01",
    "max": "2025-12-31"
  },
  "total_amount": {
    "min": 1000,
    "max": null
  }
}

Response

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

Example Response

{
  "status": 200,
  "page": 1,
  "total_pages": 3,
  "results_per_page": 50,
  "total_results": 112,
  "data": [
    {
      "id": 42,
      "category": "contract",
      "other_category_id": null,
      "contract_id": 17,
      "owner_side_amount": "3500.00",
      "client_side_amount": "2000.00",
      "total_amount": "5500.00",
      "date": "2025-03-10",
      "title": null,
      "status": "confirmed",
      "created_by": 3,
      "date_created": "2025-03-10 14:22:00",
      "date_updated": null,
      "commissions": [
        {
          "id": 5,
          "side": "owner_side",
          "partner_id": 8,
          "side_total_commission": "3500.00",
          "partner_commission_amount": "1000.00"
        }
      ],
      "contacts": [23, 45]
    }
    //Rest of the data...
  ]
}

Get single income

/api/incomes/{id} (GET)

Get a single income record by its id.

Request

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

Example Response

{
  "status": 200,
  "data": {
    "id": 42,
    "category": "contract",
    "other_category_id": null,
    "contract_id": 17,
    "owner_side_amount": "3500.00",
    "client_side_amount": "2000.00",
    "total_amount": "5500.00",
    "date": "2025-03-10",
    "title": null,
    "notes": "Commission from property sale",
    "status": "confirmed",
    "created_by": 3,
    "date_created": "2025-03-10 14:22:00",
    "date_updated": null,
    "commissions": [
      {
        "id": 5,
        "side": "owner_side",
        "partner_id": 8,
        "side_total_commission": "3500.00",
        "partner_commission_amount": "1000.00"
      }
    ],
    "contacts": [23, 45]
  }
}

Response

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

Get income statuses

/api/incomes/statuses (GET)

Fetch the available income statuses.

Request

• Method: GET
• Headers: Include authentication headers.

Response

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

Example Response

{
  "status": 200,
  "data": [
    {
      "id": "pending",
      "name": "Pending"
    },
    {
      "id": "confirmed",
      "name": "Confirmed"
    }
  ]
}

Get income categories

/api/incomes/categories (GET)

Fetch the available income categories.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of available income categories.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": "contract",
      "name": "Contract"
    },
    {
      "id": "valuation",
      "name": "Valuation"
    },
    {
      "id": "referral",
      "name": "Referral"
    },
    {
      "id": "other",
      "name": "Other"
    }
  ]
}

Get income other categories

/api/incomes/other-categories (GET)

Fetch the available custom subcategories used when category is other.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of custom "other" income subcategories.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Consulting Fee"
    },
    {
      "id": 2,
      "name": "Administrative Service"
    }
  ]
}

Get expense categories

/api/incomes/expense-categories (GET)

Fetch the available expense categories. Useful when working with commission expenses linked to incomes.

Request

• Method: GET
• Headers: Include authentication headers.

Response

• 200 OK: Returns a JSON array of expense categories.

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "name": "Partner Commission"
    }
  ]
}