Edit a deal

PATCHhttps://secure.alterestate.com/api/v1/deals/edit/{uid}/

Updates fields on an existing deal. Send only the fields that change.

Authentication

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

Path parameters

uidstringrequired: Deal uid from List deals or Retrieve a deal.Example: AB12cdEF34

Deal

Field	Type	Description
`name`	string	Deal name. Example: `Ana Martinez · Naco apartment`.
`notes`	string	Internal notes. Example: `Visit confirmed for Saturday at 10:00.`.
`status`	string	open, won, lost or closed. Example: `open`.
`lost_reason`	string	Free-text note when the deal is lost. Example: `Bought with another agency.`.

Funnel

Field	Type	Description
`stage`	string	Stage uid. Must belong to the deal’s current pipeline. Get uids from Pipelines and stages. Example: `STGVISIT01`.
`pipeline`	string	Pipeline uid. Send it together with a stage of that pipeline when moving the deal to another funnel. Example: `PIPE01SALE`.

People

Field	Type	Description
`agent`	string	Uid of the agent who owns the deal. Example: `IZHIZ6C3Z6`.
`principal_contact`	string	Contact uid of the principal contact. Example: `D9dEML2g39`.
`contacts`	array	Contact uids linked to the deal. Replaces the list. Example: `["D9dEML2g39"]`.
`related_agents`	array	Follower user uids. Replaces the list. Example: `["IZHIZ6C3Z6"]`.

Budget and search

Field	Type	Description
`budget`	number	Budget in currency. Example: `190000`.
`currency`	string	Budget currency, for example USD or DOP. Example: `USD`.
`listing`	number	1 sale, 2 rent, 3 nightly rental, 4 furnished rental. Example: `1`.
`rooms`	number	Bedrooms the contact is looking for. Example: `2`.
`bathrooms`	number	Bathrooms. Example: `2`.
`parkings`	number	Parking spaces. Example: `1`.

Links

Field	Type	Description
`properties`	array	Property uids linked to the deal. Replaces the list. Example: `["JSORJ9S5AY"]`.
`tag`	string	Tag uid, or null to clear it. Example: `TAG01HOT`.

Custom fields

Field	Type	Description
`custom_fields`	object	Keys must match active deal custom fields. Omitted keys are left unchanged. Send null to clear a key. Example: `{"lead_score": 90}`.

Example request

PATCH

curl --request PATCH \
  --url 'https://secure.alterestate.com/api/v1/deals/edit/AB12cdEF34/' \
  --header 'Authorization: Token your_api_key_here' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "stage": "STGVISIT01",
  "budget": 190000,
  "currency": "USD",
  "notes": "Visit confirmed for Saturday at 10:00.",
  "custom_fields": {
    "lead_score": 90
  }
}'

Example response

200 OK

{
  "uid": "AB12cdEF34",
  "name": "Ana Martinez · Naco apartment",
  "status": "open",
  "is_prospect": false,
  "notes": "Wants to visit on Saturday.",
  "budget": "185000.00",
  "currency": "USD",
  "value": "185000.00",
  "pipeline_uid": "PIPE01SALE",
  "pipeline_name": "Sales",
  "stage": {
    "uid": "STGVISIT01",
    "name": "Showing",
    "order": 2,
    "pipeline": "PIPE01SALE",
    "pipeline_string": "Sales",
    "is_active": true,
    "closing_probability": 40
  },
  "principal_contact": {
    "uid": "D9dEML2g39",
    "full_name": "Ana Martinez",
    "email": "ana@example.com",
    "phone": "+18095550123"
  },
  "agent": {
    "uid": "IZHIZ6C3Z6",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "email": "john@agency.com"
  },
  "related_agents": [],
  "contacts": [],
  "properties": [],
  "linked_properties": [
    {
      "property_uid": "JSORJ9S5AY",
      "unit_property_uid": null,
      "name": "Modern apartment in Naco",
      "is_children": false
    }
  ],
  "listing": 1,
  "rooms": 2,
  "bathrooms": "2.0",
  "parkings": 1,
  "custom_fields": {
    "lead_score": 90,
    "client_type": "investor"
  },
  "custom_fields_read": [
    {
      "key": "lead_score",
      "label": "Lead score",
      "field_type": "number",
      "value": 90,
      "display_value": "90",
      "show_on_list": true
    }
  ],
  "can_edit": true,
  "timestamp": "2026-03-01T23:40:12.000000-04:00",
  "updated": "2026-03-04T15:12:01.110000-04:00"
}

400 Bad Request

{
  "stage": [
    "La etapa «New» pertenece al embudo «Rentals» y el negocio está en «Sales». Solo se puede mover entre etapas del mismo embudo."
  ]
}

404 Not Found

{
  "detail": "Not found."
}

Partial updates

Send only the fields you want to change. The response is the full deal, the same shape as Retrieve a deal, including pipeline, stage, contact, linked properties and custom fields.

Moving a deal between stages

To move inside the same funnel, send stage with a stage uid from that pipeline.
To move to another funnel, send pipeline and a stage that belongs to the new pipeline in the same request.
A stage from a different funnel returns 400. The message is in Spanish and names both funnels.

custom_fields is an object of key to value. Keys come from GET /api/v1/custom-fields/?app=deals. On PATCH, keys you omit stay as they are. The types match Leads: text and textarea are strings, number is a number, boolean is true or false, date is YYYY-MM-DD, select is an option value.

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, invalid, or the user cannot open this deal.
404	The resource or route does not exist.
429	Too many requests. Wait and retry.
500	Server error while processing the request.

Frequently asked questions

Do I have to send every deal field?

No. PATCH updates only the fields you send. contacts, related_agents and properties are the exception: sending any of them replaces that whole list.

How do I move a deal to the next stage?

PATCH /api/v1/deals/edit/{uid}/ with stage set to a stage uid from GET /api/v1/deals/stages/?pipeline={pipeline_uid}. The stage must belong to the deal’s current pipeline.

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