--- title: "Get a list of deals" description: "GET /deals โ€” Returns the account's deals. Each deal belongs to one primary contact and moves through your pipeline as pending, then won or lost." canonical_url: https://developer.onepagecrm.com/api/reference/deals/get-deals/ source: Markdown mirror of https://developer.onepagecrm.com/api/reference/deals/get-deals/ --- `GET /deals` Returns the account's deals. Each deal belongs to one primary contact and moves through your pipeline as pending, then won or lost. Resource: [Deals](https://developer.onepagecrm.com/api/reference/deals/) ยท [API Reference](https://developer.onepagecrm.com/api/reference/) ## Request ```bash curl "https://app.onepagecrm.com/api/v3/deals" \ -u $user_id:$api_key ``` Authentication is HTTP Basic โ€” `user_id` as username, `api_key` as password. See https://developer.onepagecrm.com/api/authentication/. ## Query parameters | Name | Type | Description | | --- | --- | --- | | `name` | string | Search deals by name | | `search` | string | Search deals by deal name, contact name or company name | | `status` | string | Return deals of a particular status (i.e. `pending`, `won`, `lost`, or `closed`) | | `stage` | integer | Return deals (of status `pending`) with specified deal stage | | `pipeline_id` | string | Return deals from the specified pipeline only | | `sales_pipeline_id` | string | Return deals referencing a specified sales pipeline only | | `owner_id` | string | Return deals owned by a specific user | | `contact_id` | string | Return deals for a specific contact (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time) | | `company_id` | string | Return deals for a specific company (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time) | | `tag` | string | Filter deals by tag (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time) | | `filter_id` | string | Apply filter to deal listing (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time) | | `fields` | string | Include related resources alongside each deal in the response. Syntax: `fields=(all)`. Use a comma-separated list to request multiple resources. Supported resources: `contacts`. When `fields=contacts(all)` is supplied, each deal entry includes a `contacts` array of full `Contact` objects (the primary contact plus any linked contacts). The short-form `linked_contacts` array on each deal is always returned regardless of this parameter. Example: `fields=contacts(all)` | | `date_filter` | string | Signals which date field to be used for only returning resources, added or edited, in a specified date range (only to be used with `since` and/or `until`, not with `modified_since` or `unmodified_since`) | | `since` | string | Specifies the start of the date range to filter resources, which have been added or edited (use with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp) | | `until` | string | Specifies the end of the date range to filter resources, which have been added or edited (use with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp) | | `modified_since` | string | Return only resources that were modified since specified time (cannot be used with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp) | | `unmodified_since` | string | Return only resources that were unmodified since specified time (cannot be used with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp) | | `include_history` | boolean | Returns deal stages history, i.e. the most recent stages for each pipeline for the deal This field is returned only when 'include_history=true' param is supplied in request (query string or request body) Format: pipeline_id => stage | | `sort_by` | string | Specify field by which to order the results (use in conjunction with `order`) | | `order` | string | Specify the order (ascending or descending) of the sort of the results (use in conjunction with `sort_by`) | | `page` | integer | Page number. Starts from 1. Default is 1. | | `per_page` | integer | Number of records to return. Maximum 100 allowed. Default is 10. | ## Responses ### 200 OK ```json { "status": 0, "message": "OK", "timestamp": 1528373119, "data": { "deals": [ { "deal": { "id": "5aaa9b059007ba08c9ebaf58", "contact_id": "5aaa9b059007ba08c9ebaf58", "owner_id": "5aba31e99007ba0f570c12f7", "pipeline_id": "5cfa87a4849d7873db082f98", "sales_pipeline_id": "5cfa87a4849d7873db082f98", "name": "Solar panels", "text": "Fingers crossed!", "stage": 50, "status": "pending", "expected_close_date": "2018-04-15", "close_date": "2018-04-15", "date": "2018-04-15", "amount": 99.99, "months": 1, "cost": 0, "margin": 99.99, "total_amount": 99.99, "total_cost": 0, "commission_base": "amount", "commission_type": "none", "commission": 0, "commission_percentage": 0, "reason_lost_id": "5aaa9b059007ba08c9ebaf58", "deal_fields": [ {} ], "has_deal_items": true, "deal_items": [ {} ], "author": "Jane D.", "has_related_notes": true, "attachments": [ {} ], "contact_info": { "contact_name": "Joe Bloggs", "company": "Big Company Inc." }, "owner": { "id": "5aba31e99007ba0f570c12f7", "name": "Joe Bloggs", "email": "joe.bloggs@example.com" }, "previous_pipeline_stages": { "5da7b67a849d78737812437c": 40 }, "created_at": "2018-03-15T16:10:45Z", "modified_at": "2018-03-15T16:10:45Z", "linked_contacts": [ { "id": "68b5edd78b3ee61b685c8692", "contact_name": "Sajed Almorsy", "company": "OnePageCRM", "photo_url": "" } ] }, "contacts": [ { "id": "5aba31ea9007ba0f570c92d4", "title": "Mr", "first_name": "Joe", "last_name": "Bloggs", "job_title": "Engineer", "starred": true, "photo_url": "https://{foo.bar}/joe-bloggs.jpg", "company_id": "5aba31ea9007ba0f570c92d5", "company_name": "Morgan's Forensic Lab", "urls": [], "phones": [], "emails": [], "address_list": [], "status": "Prospect", "status_id": "5e31e030849d781e837b6ba1", "tags": [ "Java", "Android", "iOS" ], "lead_source_id": "email_web", "lead_source": "Email or Web", "background": "I met Joe Bloggs at the annual Eco Conference in Florida. Her company currently provides solar panels (along with a lot of other stuff) to the State Government of California, Nevada, Oregon, Arizona and Utah for capital building projects. Her current supplier is crazy expensive! I've asked to be able to tender for their next order.", "owner_id": "5aba31e99007ba0f570c92a5", "custom_fields": [], "letter": "b", "pending_deal": true, "total_pendings": 999.99, "total_deals_count": 3, "company_size": 1, "sales_closed_for": [ "5aba31e99007ba0f570c12f7" ], "closed_sales": [], "google_contacts_data": {}, "created_at": "2018-05-16T11:52:09Z", "modified_at": "2018-05-16T11:52:09Z" } ] } ], "total_count": 1, "page": 1, "per_page": 10, "max_page": 1 } } ``` Standard error responses: 400, 401, 403, 404, 409, 500 โ€” shared across the API. See https://developer.onepagecrm.com/api/errors/. ## Related guides - [Authentication](https://developer.onepagecrm.com/api/authentication/) - [Errors](https://developer.onepagecrm.com/api/errors/) - [Rate limits](https://developer.onepagecrm.com/api/rate-limits/) - [Pagination](https://developer.onepagecrm.com/api/pagination/) - [Sorting & time filters](https://developer.onepagecrm.com/api/sorting/)