# Edit a deal

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

Source: https://dev.alterestate.com/deals/edit
Last updated: 2026-10-13

```http
PATCH https://secure.alterestate.com/api/v1/deals/edit/{uid}/
```

Authentication: `Authorization: Token your_api_key_here`

| Parameter | In | Type | Required | Group | Description |
| --- | --- | --- | --- | --- | --- |
| `uid` | path | string | yes |  | Deal uid from List deals or Retrieve a deal. |
| `name` | body | string | no | Deal | Deal name. |
| `notes` | body | string | no | Deal | Internal notes. |
| `status` | body | string | no | Deal | open, won, lost or closed. |
| `lost_reason` | body | string | no | Deal | Free-text note when the deal is lost. |
| `stage` | body | string | no | Funnel | Stage uid. Must belong to the deal’s current pipeline. Get uids from Pipelines and stages. |
| `pipeline` | body | string | no | Funnel | Pipeline uid. Send it together with a stage of that pipeline when moving the deal to another funnel. |
| `agent` | body | string | no | People | Uid of the agent who owns the deal. |
| `principal_contact` | body | string | no | People | Contact uid of the principal contact. |
| `contacts` | body | array | no | People | Contact uids linked to the deal. Replaces the list. |
| `related_agents` | body | array | no | People | Follower user uids. Replaces the list. |
| `budget` | body | number | no | Budget and search | Budget in currency. |
| `currency` | body | string | no | Budget and search | Budget currency, for example USD or DOP. |
| `listing` | body | number | no | Budget and search | 1 sale, 2 rent, 3 nightly rental, 4 furnished rental. |
| `rooms` | body | number | no | Budget and search | Bedrooms the contact is looking for. |
| `bathrooms` | body | number | no | Budget and search | Bathrooms. |
| `parkings` | body | number | no | Budget and search | Parking spaces. |
| `properties` | body | array | no | Links | Property uids linked to the deal. Replaces the list. |
| `tag` | body | string | no | Links | Tag uid, or null to clear it. |
| `custom_fields` | body | object | no | Custom fields | Keys must match active deal custom fields. Omitted keys are left unchanged. Send null to clear a key. |

Example request:

```bash
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
  }
}'
```

Response 200 OK:

```json
{
  "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"
}
```

Response 400 Bad Request:

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

Response 404 Not Found:

```json
{
  "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

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. |

> PATCH is rejected with 403 and "No tienes permiso para editar este negocio." unless can_edit is true. That is true for the assigned agent, a follower, a user allowed to change deals, or a deal in the basket.

- [Retrieve a deal](https://dev.alterestate.com/deals/retrieve)
- [Stage uids](https://dev.alterestate.com/deals/pipelines)
- [List deals](https://dev.alterestate.com/deals/list)

## FAQ

### 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.