# List deals 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. Source: https://dev.alterestate.com/deals/list Last updated: 2026-10-13 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/ | ```http GET https://secure.alterestate.com/api/v1/deals/list/ ``` Authentication: `Authorization: Token your_api_key_here` | Parameter | In | Type | Required | Group | Description | | --- | --- | --- | --- | --- | --- | | `page` | query | integer | no | Pagination | Page number. Defaults to 1. | | `page_size` | query | integer | no | Pagination | Results per page. Defaults to 25. | | `status` | query | string | no | Pipeline | open, won, lost or closed. Separate several with commas. | | `pipeline` | query | string | no | Pipeline | Pipeline uid. Get it from Pipelines and stages. | | `stage` | query | string | no | Pipeline | Stage uid. The stage must belong to the pipeline you are filtering. | | `archived` | query | boolean | no | Pipeline | true returns archived deals. false returns active deals. Omit it to receive both. | | `agent` | query | string | no | People | Agent uid. agent_uid is an alias. | | `contacts` | query | string | no | People | Contact uid. Matches the principal contact or any contact on the deal. | | `name` | query | string | no | People | Partial deal name, accent insensitive. Several words must all match. | | `created_by` | query | string | no | People | Uid of the user who created the deal. | | `related_agents` | query | string | no | People | Uid of a follower on the deal. | | `startDate` | query | date | no | Dates | Deals created on or after this date (YYYY-MM-DD). | | `endDate` | query | date | no | Dates | Deals created on or before this date (YYYY-MM-DD). | | `wonStartDate` | query | date | no | Dates | Won on or after this date. | | `wonEndDate` | query | date | no | Dates | Won on or before this date. | | `lostStartDate` | query | date | no | Dates | Lost on or after this date. | | `lostEndDate` | query | date | no | Dates | Lost on or before this date. | | `currency` | query | string | no | Budget | Currency of value_min and value_max: USD, DOP, MXN, COP, CRC or GTQ. Converted to USD on the server. | | `value_min` | query | number | no | Budget | Minimum budget. Send currency when the amount is not in USD. | | `value_max` | query | number | no | Budget | Maximum budget. | | `property` | query | string | no | Property | Property uid linked to the deal. Separate several with commas. | | `include_fields` | query | string | no | Columns | Comma-separated extra columns. Omitted fields stay out of each result. See Choosing columns below. | | `sort` | query | string | no | Sorting | Field to sort by. Prefix with - for descending. Defaults to newest first. See Sorting below. | Example request: ```bash 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' ``` Response 200 OK: ```json { "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: ```text 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: ```json { "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: ```json { "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. | > The contact stays with whoever registered it. The deal belongs to whoever generated the lead, so a deal can appear for an agent even when the contact’s owner is someone else. - [Retrieve a deal](https://dev.alterestate.com/deals/retrieve) - [Pipelines and stages](https://dev.alterestate.com/deals/pipelines) - [Edit a deal](https://dev.alterestate.com/deals/edit) - [List round robins](https://dev.alterestate.com/deals/round-robins) - [Create a lead](https://dev.alterestate.com/leads) ## FAQ ### 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.