Custom fields

GEThttps://secure.alterestate.com/api/v1/custom-fields/schema/

Lists the custom fields defined for your company. Use the keys when you send a lead, so values land on the contact, the deal, or both.

Custom fields are created in the dashboard under Settings → Fields → Custom fields. This endpoint returns only the fields of the company that owns the API token, and only those that are active and enabled for the API.

Authentication

Send Authorization: Token your_api_key_here. Account token. Keep it on your server.

Query parameters

appstring: Module to list: deals, contacts, properties or project_units. For leads, call it for deals and for contacts. Omit it to return every module.Example: deals
groupboolean: When true, fields come back grouped by module under schema instead of a flat fields list.Example: true

Example request

GET

curl --request GET \
  --url 'https://secure.alterestate.com/api/v1/custom-fields/schema/?app=deals' \
  --header 'Authorization: Token your_api_key_here' \
  --header 'Accept: application/json'

Example response

200 OK

{
  "fields": [
    {
      "key": "client_type",
      "label": "Client type",
      "field_type": "select",
      "app": "deals",
      "description": "How this person plans to buy.",
      "placeholder": null,
      "help_text": null,
      "is_required": false,
      "options": [
        {
          "label": "Investor",
          "value": "investor"
        },
        {
          "label": "End user",
          "value": "end_user"
        }
      ],
      "validation": {},
      "default_value": null,
      "show_on_filters": true
    },
    {
      "key": "lead_score",
      "label": "Lead score",
      "field_type": "number",
      "app": "deals",
      "description": null,
      "placeholder": null,
      "help_text": null,
      "is_required": false,
      "options": [],
      "validation": {
        "minimum": 0,
        "maximum": 100
      },
      "default_value": null,
      "show_on_filters": false
    }
  ],
  "total": 2
}

200 Grouped

{
  "schema": {
    "deals": [
      {
        "key": "client_type",
        "label": "Client type",
        "field_type": "select",
        "app": "deals"
      }
    ],
    "contacts": [
      {
        "key": "original_source",
        "label": "Original source",
        "field_type": "text",
        "app": "contacts"
      }
    ]
  },
  "total": 2
}

Response fields

Field	Use it for
key	The name you send inside custom_fields when you create a lead.
label	The name shown to agents in the dashboard.
field_type	text, textarea, number, boolean, date, datetime, select or multiselect.
app	deals or contacts for leads. properties and project_units are for listings.
is_required	When you include this key, the value cannot be empty.
options	For select and multiselect. Send the value, not the label.
validation	Rules such as minimum, maximum, min_length, max_length or a regex.
show_on_filters	Whether agents can filter lists by this field.

Sending values on a lead

Pass the keys you just listed in custom_fields on POST /api/v1/leads/. Two formats are accepted.

Flat format (recommended)

Use each field key as the JSON key. AlterEstate routes every value to the contact, the deal or both, depending on which module owns the key. If the same key exists in both, the value is written to both.

JSON

{
  "full_name": "John Doe",
  "phone": "8091234567",
  "email": "johndoe@email.com",
  "property_uid": "KNM6135T3B",
  "custom_fields": {
    "lead_score": 85,
    "client_type": "investor",
    "visit_date": "2026-06-12",
    "original_source": "instagram",
    "has_financing": true
  }
}

Namespaced format

Use it when the same key exists in both modules but should only be written to one.

JSON

{
  "full_name": "John Doe",
  "phone": "8091234567",
  "email": "johndoe@email.com",
  "custom_fields": {
    "deals": {
      "lead_score": 85,
      "client_type": "investor"
    },
    "contacts": {
      "original_source": "instagram",
      "has_financing": true
    }
  }
}

Field types

Type	JSON value	Example
text	string	"Beach house"
textarea	string	"Long notes..."
number	number or numeric string	85 or "85"
boolean	bool, "true", "si" or 1	true
date	YYYY-MM-DD	"2026-06-12"
datetime	ISO 8601	"2026-06-12T14:30:00Z"
select	string matching an option value	"investor"
multiselect	array of option values	["sea", "city"]

Validation

Every key must match an active custom field of your company.
select and multiselect values must match an option value, not its label.
Min/max, length and regex rules defined on the field are enforced.
A required field must have a value when you include its key. Leaving the key out of a lead does not reject the request.
Invalid values return 400 with one error per key. Validation messages are returned in Spanish.

Where values appear

In the Custom fields section of the contact and the deal.
As list columns, when the field has show on list enabled.
In filters, reports and the API responses for that record.
In a timeline activity so the assigned agent sees exactly what arrived.

Status codes

Status	Meaning
200	The request succeeded.
400	A parameter or the body is invalid. The response names the field.
401	The token is missing or invalid.
404	The resource or route does not exist.
429	Too many requests. Wait and retry.
500	Server error while processing the request.

Send a lead

Frequently asked questions

How do I list the custom fields of my company?

Send GET /api/v1/custom-fields/schema/ with your account token. Add app=deals or app=contacts to limit the list. The response only includes fields of the company that owns the token.

Which value do I send for a dropdown custom field?

Send the option value from the schema, for example investor, not the label shown to agents, such as Investor.

Last updated 2026-10-13. Questions? Emailengineering@alterestate.com.