List deals

GEThttps://secure.alterestate.com/api/v1/deals/list/

Returns the deals your account can open, one page at a time. Filter by pipeline, stage, status, agent, contact, dates and budget, and choose extra columns with include_fields.

Use the Deals API to read and update the sales pipeline in your AlterEstate account. Every request uses the account token. Results follow that user’s permissions: an agent sees their own deals, a team leader sees the teams they lead, and a user who can view every deal sees the company.

Capability	Endpoint
List deals	GET /api/v1/deals/list/
Get one deal	GET /api/v1/deals/view/{uid}/
List pipelines and stages	GET /api/v1/deals/pipeline/ and GET /api/v1/deals/stages/
Update a deal	PATCH /api/v1/deals/edit/{uid}/
List round robins	GET /api/v1/campaigns/round-robins/

Authentication

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

Pagination

pageinteger: Page number. Defaults to 1.Example: 1
page_sizeinteger: Results per page. Defaults to 25.Example: 25

Pipeline

statusstring: open, won, lost or closed. Separate several with commas.Example: open
pipelinestring: Pipeline uid. Get it from Pipelines and stages.Example: PIPE01SALE
stagestring: Stage uid. The stage must belong to the pipeline you are filtering.Example: STGVISIT01
archivedboolean: true returns archived deals. false returns active deals. Omit it to receive both.Example: false

People

agentstring: Agent uid. agent_uid is an alias.Example: IZHIZ6C3Z6
contactsstring: Contact uid. Matches the principal contact or any contact on the deal.Example: D9dEML2g39
namestring: Partial deal name, accent insensitive. Several words must all match.Example: Naco
created_bystring: Uid of the user who created the deal.Example: IZHIZ6C3Z6
related_agentsstring: Uid of a follower on the deal.Example: IZHIZ6C3Z6

Dates

startDatedate: Deals created on or after this date (YYYY-MM-DD).Example: 2026-03-01
endDatedate: Deals created on or before this date (YYYY-MM-DD).Example: 2026-03-31
wonStartDatedate: Won on or after this date.Example: 2026-03-01
wonEndDatedate: Won on or before this date.Example: 2026-03-31
lostStartDatedate: Lost on or after this date.Example: 2026-03-01
lostEndDatedate: Lost on or before this date.Example: 2026-03-31

Budget

currencystring: Currency of value_min and value_max: USD, DOP, MXN, COP, CRC or GTQ. Converted to USD on the server.Example: USD
value_minnumber: Minimum budget. Send currency when the amount is not in USD.Example: 150000
value_maxnumber: Maximum budget.Example: 250000

Property

propertystring: Property uid linked to the deal. Separate several with commas.Example: JSORJ9S5AY

Columns

include_fieldsstring: Comma-separated extra columns. Omitted fields stay out of each result. See Choosing columns below.Example: pipeline,agent_read,principal_contact_email,custom_fields,linked_properties

Sorting

sortstring: Field to sort by. Prefix with - for descending. Defaults to newest first. See Sorting below.Example: -timestamp

Example request

GET

curl --request GET \
  --url 'https://secure.alterestate.com/api/v1/deals/list/?status=open&pipeline=PIPE01SALE&include_fields=pipeline%2Cagent_read%2Cprincipal_contact_email%2Ccustom_fields%2Clinked_properties' \
  --header 'Authorization: Token your_api_key_here' \
  --header 'Accept: application/json'

Example response

200 OK

{
  "count": 42,
  "total": "2450000.00",
  "next": "https://secure.alterestate.com/api/v1/deals/list/?page=2",
  "previous": null,
  "results": [
    {
      "uid": "AB12cdEF34",
      "name": "Ana Martinez · Naco apartment",
      "principal_contact": "Ana Martinez",
      "principal_contact_detail": {
        "uid": "D9dEML2g39",
        "full_name": "Ana Martinez"
      },
      "budget": "185000.00",
      "currency": "USD",
      "stage": "Showing",
      "stage_detail": {
        "uid": "STGVISIT01",
        "name": "Showing"
      },
      "agent_uid": "IZHIZ6C3Z6",
      "timestamp": "2026-03-01T23:40:12.000000-04:00",
      "status": "open",
      "has_access": true,
      "seen": true,
      "engagement": {
        "is_hot": false,
        "score": 0,
        "reasons": [],
        "window_days": 7
      },
      "pipeline": "Sales",
      "agent_read": "John Smith",
      "principal_contact_email": "ana@example.com",
      "principal_contact_phone": "+18095550123",
      "custom_fields": {
        "lead_score": "90",
        "client_type": "Investor"
      },
      "linked_properties": [
        {
          "property_uid": "JSORJ9S5AY",
          "unit_property_uid": null,
          "name": "Modern apartment in Naco",
          "is_children": false
        }
      ]
    }
  ],
  "filters": {
    "status": "open",
    "pipeline": {
      "id": 12,
      "name": "Sales"
    }
  }
}

Response

Field	Description
count	Number of deals that match the filters.
total	Sum of those deals’ budgets, normalized to USD.
next, previous	URLs of the next and previous pages. null on the last or first page.
results	Deals on this page. Extra keys appear only when you request them with include_fields.
filters	Echo of the query. agent, pipeline, property, tag and round_robin are resolved to small objects.

Fields always returned

Every deal in results includes these fields, whether or not you send include_fields.

Field	Description
uid	Public deal identifier. Use it to retrieve or edit the deal.
name	Deal name.
status	open, won, lost or closed.
budget, currency	Budget in the deal’s currency. budget is a decimal string.
principal_contact	Principal contact’s name, or null.
principal_contact_detail	Object with uid and full_name.
stage	Stage name.
stage_detail	Object with uid and name.
agent_uid	Uid of the assigned agent.
timestamp	When the deal was created.
has_access	true when the token user is the agent or a follower.
seen	true when this user has already opened the deal.
engagement	Heat score: is_hot, score, reasons and window_days.

Choosing columns with include_fields

include_fields is a comma-separated list of extra columns. Names that are not in the list below are ignored. Repeat the same names on every page of a sync so the shape stays stable.

Example

GET /api/v1/deals/list/?status=open&include_fields=pipeline,agent_read,principal_contact_email,custom_fields,linked_properties

include_fields value	Adds
pipeline	Pipeline name.
stage	Already returned. Listing it does not change the payload.
agent, agent_read	Assigned agent id, and the agent’s name.
related_agents	Follower user ids.
principal_contact_email, principal_contact_phone	Email and phone of the principal contact.
via	Lead source name.
tag	Tag name.
created_by	Name of the user who created the deal.
team	Name of the assigned agent’s team.
next_activity, updated, won_time, rotten_time	Next activity, last update, won date, and when the deal went stale on its stage.
contacts_count, activities_count, activities_completed_count	Contact and activity counters.
reason	Lost-reason name.
closed_deal_cid, closed_deal_is_completed, operation, closed_deal_type, property	Closing sheet: number, whether it is complete, operation, closing type, and property name. Empty unless status is won.
inbox_origin	whatsapp, instagram or facebook when the deal started in Inbox.
utm_source, utm_campaign, utm_medium, utm_content, utm_term	UTM tags captured with the lead.
campaign_name, adset_name, form_name, platform	Ad campaign, ad set, form and platform.
linked_properties	Properties and units linked to the deal. See below.
custom_fields	Custom fields marked “show on list”. See below.

Custom fields

Add custom_fields to include_fields. The value is an object keyed by each deal custom field that the agency marked to show on the list. Fields that are hidden from the list are omitted here; retrieve the deal to read every custom field.

custom_fields

{
  "custom_fields": {
    "lead_score": "90",
    "client_type": "Investor"
  }
}

A column named custom_field:lead_score in the dashboard is the same data. The API still expects the token custom_fields, not one token per key. List the keys your agency uses with GET /api/v1/custom-fields/?app=deals.

Linked properties

Add linked_properties to include_fields. Each item is a property on the deal. When the row is a project unit, property_uid is the parent listing and unit_property_uid is the unit. For a normal listing, unit_property_uid is null and is_children is false.

linked_properties

{
  "linked_properties": [
    {
      "property_uid": "JSORJ9S5AY",
      "unit_property_uid": null,
      "name": "Modern apartment in Naco",
      "is_children": false
    }
  ]
}

Sorting

Value	Sorts by
timestamp / -timestamp	Date the deal was created. Default is newest first.
updated / -updated	Last update.
name, status, stage, pipeline, agent	Name, status, stage order, pipeline or agent first name.
budget / -budget	Budget in USD. value is an alias.
principal_contact, email, principal_contact_phone	Contact name, email or phone.
won_time, lost_time, next_activity, last_activity	Won date, lost date, next activity or last activity.
utm_source, utm_campaign, campaign_name, platform	Marketing fields. Request them with include_fields if you also need them in the payload.

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

How do I add columns to the deals list?

Send include_fields as a comma-separated query parameter, for example include_fields=pipeline,agent_read,principal_contact_email,custom_fields,linked_properties. Columns you do not name are left out of each result.

How do I include deal custom fields in the list?

Add custom_fields to include_fields. The object only contains deal custom fields marked to show on the list. GET /api/v1/custom-fields/?app=deals returns the keys.

How do I see which property a deal is about?

Add linked_properties to include_fields. Each item has property_uid, and unit_property_uid when the row is a project unit.

How many deals does each page return?

25 by default. Pass page_size to change it and page to move forward. next is null on the last page.

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