# Retrieve a deal

Returns one deal: pipeline, stage, contact, agent, budget, linked properties, notes and custom fields.

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

```http
GET https://secure.alterestate.com/api/v1/deals/view/{uid}/
```

Authentication: `Authorization: Token your_api_key_here`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uid` | path | string | yes | Public deal identifier. List deals and Leads both return it as uid or deal_uid. |

Example request:

```bash
curl --request GET \
  --url 'https://secure.alterestate.com/api/v1/deals/view/AB12cdEF34/' \
  --header 'Authorization: Token your_api_key_here' \
  --header 'Accept: application/json'
```

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 401 Unauthorized:

```json
{
  "message": "Unauthorized user data",
  "error": "401"
}
```

Response 404 Not Found:

```json
{
  "detail": "Not found."
}
```

## Key fields

| Field | Description |
| --- | --- |
| uid | Public identifier. Use it in Edit a deal. |
| status | open, won, lost or closed. |
| pipeline_uid, pipeline_name | Pipeline the deal sits in. Stage uids come from Pipelines and stages. |
| stage | Current stage, including uid, name and order. |
| principal_contact | Main contact, with uid, name, email and phone. |
| agent, related_agents | Assigned agent and followers. |
| budget, currency, value | Budget in the deal currency, and the same amount normalized to USD in value. |
| listing | 1 sale, 2 rent, 3 nightly rental, 4 furnished rental. |
| rooms, bathrooms, parkings | What the contact is looking for. |
| properties | Property cards linked to the deal. |
| linked_properties | Compact links: property_uid, unit_property_uid, name and is_children. Always included on this endpoint. |
| custom_fields | Every deal custom field value, keyed by field key. |
| custom_fields_read | The same values with label, type and display_value. |
| can_edit | true when this token can PATCH the deal. |
| notes | Internal notes. |

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

> A 401 means the deal exists but this user cannot open it. A 404 means the uid does not match a deal in the account.

- [List deals](https://dev.alterestate.com/deals/list)
- [Pipelines and stages](https://dev.alterestate.com/deals/pipelines)
- [Edit a deal](https://dev.alterestate.com/deals/edit)

## FAQ

### Where do I find a deal uid?

Each result of GET /api/v1/deals/list/ includes uid. Creating a lead also returns deal_uid.

### Does retrieve accept include_fields?

No. GET /api/v1/deals/view/{uid}/ always returns the full deal, including linked_properties and every custom field. include_fields only applies to the list.