Retrieve a deal

GEThttps://secure.alterestate.com/api/v1/deals/view/{uid}/

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

Authentication

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

Path parameters

uidstringrequired: Public deal identifier. List deals and Leads both return it as uid or deal_uid.Example: AB12cdEF34

Example request

GET

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

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"
}

401 Unauthorized

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

404 Not Found

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

Frequently asked questions

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.

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