---
title: "Get a list of contacts"
description: "GET /contacts — Returns the contacts you can access, sorted by name. Filter by company_id, email, phone, tag, status_id, starred, owner_id and more."
canonical_url: https://developer.onepagecrm.com/api/reference/contacts/get-contacts/
source: Markdown mirror of https://developer.onepagecrm.com/api/reference/contacts/get-contacts/
---

`GET /contacts`

Returns the contacts you can access, sorted by name. Filter by company_id, email, phone, tag, status_id, starred, owner_id and more. has_actions and has_actions_for_me are mutually exclusive, as are lead_source and lead_source_id. sort_by accepts created_at, modified_at, first_name, last_name, company_name and name, each with order=asc or desc (ascending is the default). When results are filtered by a created_at or modified_at date range and no sort_by is given, they default to newest first.

Resource: [Contacts](https://developer.onepagecrm.com/api/reference/contacts/) · [API Reference](https://developer.onepagecrm.com/api/reference/)

## Request

```bash
curl "https://app.onepagecrm.com/api/v3/contacts" \
  -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 |
| --- | --- | --- |
| `team` | boolean | Include contacts owned by other users |
| `search` | string | Search contacts by contact name, company name or phone number |
| `phone` | string | Search contacts by phone number |
| `url` | string | Search contacts by web address |
| `action_stream` | boolean | Only return results that are also in action stream |
| `has_actions` | boolean | Only return contacts who are owned by the logged user, and have actions for any user (can not query by `has_actions` and `has_actions_for_me` at the same time) |
| `has_actions_for_me` | boolean | Only return contacts who are owned by, and have actions for, the logged user (can not query by `has_actions` and `has_actions_for_me` at the same time) |
| `has_actions_today` | boolean | Only return contacts who are owned by, and have actions today for, the logged user |
| `pending_deal` | boolean | Only return contacts who have a pending deal |
| `starred` | boolean | Only return contacts who are starred |
| `waiting` | boolean | Only return contacts, for whom I have a next action, of status `waiting` |
| `email` | string | Return contacts whose email matches that provided with this query param |
| `letter` | string | Return contacts whose last name begins with specified letter (or company name, if last name not present) |
| `custom_field_id` | string | Filter contacts by custom field value (combine with `custom_field_value`) |
| `custom_field_value` | string | Filter contacts by custom field value (combine with `custom_field_id`) |
| `lead_source` | string | Return contacts of a specific lead source (only use one of `lead_source` and `lead_source_id` at a time) |
| `lead_source_id` | string | Return contacts of a specific lead source (only use one of `lead_source` and `lead_source_id` at a time) |
| `status_id` | string | Return contacts of a particular status |
| `not_linked_with` | string | Only return contacts who are not linked to a particular company (company's id expected here - cannot be used in conjunction with `company_id` param) |
| `owner_id` | string | Return contacts owned by a specific user |
| `company_id` | string | Return contacts from a specific company (only use one of `company_id`, `tag` or `filter_id` at a time) |
| `tag` | string | Filter contacts by tag (only use one of `company_id`, `tag` or `filter_id` at a time) |
| `filter_id` | string | Apply filter to contact listing (only use one of `company_id`, `tag` or `filter_id` at a time) |
| `fields` | string | Include related resources alongside each contact in the response. Syntax: `fields=<resource>(all)`. Use a comma-separated list to request multiple resources. Each requested resource is returned as an array of full objects nested under the matching key inside the contact entry (e.g. `fields=calls(all)` adds a `calls` array next to `contact` for each item in the `contacts` array). Supported resources: `deals`, `notes`, `calls`, `meetings`, `pinned_attachments`. Examples: `fields=calls(all)` `fields=calls(all),notes(all)` `fields=deals(all),notes(all),calls(all),meetings(all),pinned_attachments(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) |
| `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": {
    "contacts": [
      {
        "contact": {
          "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": {
            "account_email": "jane.doe@example.com",
            "id": "342c5b5c08d4b0b2",
            "saved_at": 1522840153
          },
          "created_at": "2018-05-16T11:52:09Z",
          "modified_at": "2018-05-16T11:52:09Z"
        },
        "next_actions": [
          {
            "id": "5aeac8789007ba56ffca92b9",
            "assignee_id": "5aaa9b009007ba08c9ebaef7",
            "contact_id": "5aba31ea9007ba0f570c92d4",
            "text": "#1 Email Jane introducing our organization",
            "status": "date_time",
            "date": "2018-05-16",
            "exact_time": 1526472000,
            "position": 1,
            "done": false,
            "done_at": "2018-05-16",
            "created_at": "2018-05-16T11:52:09Z",
            "modified_at": "2018-05-16T12:52:09Z"
          }
        ],
        "next_action": {
          "id": "5aeac8789007ba56ffca92b9",
          "assignee_id": "5aaa9b009007ba08c9ebaef7",
          "contact_id": "5aba31ea9007ba0f570c92d4",
          "text": "#1 Email Jane introducing our organization",
          "status": "date_time",
          "date": "2018-05-16",
          "exact_time": 1526472000,
          "position": 1,
          "done": false,
          "done_at": "2018-05-16",
          "created_at": "2018-05-16T11:52:09Z",
          "modified_at": "2018-05-16T12:52:09Z"
        },
        "queued_actions": [
          {
            "id": "5aeac8789007ba56ffca92b9",
            "assignee_id": "5aaa9b009007ba08c9ebaef7",
            "contact_id": "5aba31ea9007ba0f570c92d4",
            "text": "#1 Email Jane introducing our organization",
            "status": "date_time",
            "date": "2018-05-16",
            "exact_time": 1526472000,
            "position": 1,
            "done": false,
            "done_at": "2018-05-16",
            "created_at": "2018-05-16T11:52:09Z",
            "modified_at": "2018-05-16T12:52:09Z"
          }
        ],
        "next_action_conflicts": [],
        "company": {
          "id": "5aba31e99007ba0f570c92ac",
          "image": "data:image/png;base64,iVBORw...",
          "name": "Crockett & Tubbs Security",
          "description": "For all your security needs",
          "phone": "(912) 644-1771",
          "photo_url": "https://example.com/someimage.png",
          "url": "https://{foo.bar}",
          "address": {
            "address": "Unit 5, Business Innovation Centre",
            "city": "Upper Newcastle",
            "state": "Galway",
            "zip_code": "H91 Y0T0",
            "country_code": "IE"
          },
          "company_fields": [
            {}
          ],
          "syncing_status": true,
          "synced_status_id": "5aaa9b039007ba08c9ebaf0a",
          "syncing_tags": true,
          "synced_tags": [
            "Java",
            "Android",
            "iOS"
          ],
          "contacts_count": 3,
          "won_deals_count": 5,
          "total_won_amount": 999.99,
          "pending_deals_count": 1,
          "total_pending_amount": 99.99,
          "contacts": [
            {}
          ],
          "pending_deals": [
            {}
          ],
          "created_at": "2018-05-16T11:52:09Z",
          "modified_at": "2018-05-16T11:52:09Z"
        },
        "deals": [
          {
            "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": {},
            "owner": {},
            "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": ""
              }
            ]
          }
        ],
        "notes": [
          {
            "id": "5afc1b69d556730b580596cb",
            "contact_id": "5ae06ef9d55673108fe8877f",
            "text": "I met Jane Doe at the ABC conference. She's interested in hearing about XYZ.",
            "date": "2018-05-16",
            "linked_deal_id": "",
            "linked_deal_name": "",
            "author": "Jane D.",
            "attachments": [],
            "created_at": "2018-05-16T11:52:09Z",
            "modified_at": "2018-05-16T11:52:09Z"
          }
        ],
        "calls": [
          {
            "id": "5afc1b69d556730b580596cb",
            "contact_id": "5ae06ef9d55673108fe8877f",
            "text": "Mary is interested in coming into the office on Tuesday.",
            "call_result": "interested",
            "call_time_int": 1525273653,
            "via": "phone",
            "phone_number": "(912) 644-1770 (mobile)",
            "recording_link": "",
            "author": "Jane D.",
            "attachments": [],
            "created_at": "2018-05-16T11:52:09Z",
            "modified_at": "2018-05-16T11:52:09Z",
            "index": 1
          }
        ],
        "meetings": [
          {
            "id": "5afc1b69d556730b580596cb",
            "contact_id": "5ae06ef9d55673108fe8877f",
            "text": "Mary is interested in coming into the office on Tuesday.",
            "meeting_time_int": 1525273653,
            "place": "Meeting room 1",
            "author": "Jane D.",
            "attachments": [],
            "created_at": "2018-05-16T11:52:09Z",
            "modified_at": "2018-05-16T11:52:09Z",
            "index": 1
          }
        ],
        "pinned_attachments": [
          {
            "id": "5afc1ea9d556730b780096db",
            "filename": "mario.jpg",
            "custom_filename": "another_mario.jpg",
            "pinned": true,
            "pinned_at": "2022-01-24T10:42:39Z",
            "size": 3841,
            "storage_provider": "amazon",
            "url": "https://{foo.bar}/mario.jpg",
            "url_expires_at": "2018-05-16T13:06:53Z",
            "thumbnail": {}
          }
        ]
      }
    ],
    "total_count": 1,
    "page": 1,
    "per_page": 10,
    "max_page": 1
  },
  "lead_sources": [
    {
      "id": "advertisement",
      "text": "Advertisement",
      "counts": 4,
      "total_count": 7,
      "action_stream_count": 2,
      "team_counts": [
        {
          "user_id": "5aba31e99007ba0f570c12f7",
          "counts": 4
        }
      ]
    }
  ],
  "statuses": [
    {
      "status": {
        "id": "5aead4809007ba56ffca942e",
        "status": "prospect",
        "text": "Prospect",
        "description": "Actively selling to these people",
        "color": "f96600",
        "counts": 3,
        "total_count": 3,
        "action_stream_count": 2,
        "team_counts": [
          {
            "user_id": "5aba31e99007ba0f570c12f7",
            "counts": 4
          }
        ]
      }
    }
  ],
  "tags": {
    "tags": [
      {
        "name": "VIP",
        "counts": 2,
        "total_count": 4,
        "action_stream_count": 1
      }
    ],
    "system_tags": [
      {
        "name": "VIP",
        "counts": 2,
        "total_count": 4,
        "action_stream_count": 1
      }
    ]
  },
  "contacts_count": {
    "all": [
      {
        "1": 1,
        "a": 2,
        "b": 2,
        "c": 1,
        "d": 1,
        "e": 0,
        "f": 0,
        "g": 3,
        "h": 0,
        "i": 3,
        "j": 0,
        "k": 0,
        "l": 2,
        "m": 2,
        "n": 3,
        "o": 0,
        "p": 2,
        "q": 0,
        "r": 0,
        "s": 0,
        "t": 1,
        "u": 1,
        "v": 1,
        "w": 0,
        "x": 1,
        "y": 1,
        "z": 0,
        "total_count": 27
      }
    ],
    "users": [
      {
        "1": 1,
        "a": 2,
        "b": 2,
        "c": 1,
        "d": 1,
        "e": 0,
        "f": 0,
        "g": 3,
        "h": 0,
        "i": 3,
        "j": 0,
        "k": 0,
        "l": 2,
        "m": 2,
        "n": 3,
        "o": 0,
        "p": 2,
        "q": 0,
        "r": 0,
        "s": 0,
        "t": 1,
        "u": 1,
        "v": 1,
        "w": 0,
        "x": 1,
        "y": 1,
        "z": 0,
        "total_count": 27,
        "user_id": "5aba31e99007ba0f570c12f7"
      }
    ]
  },
  "team_stream": {
    "all": 10,
    "users": [
      {
        "user_id": "5aba31e99007ba0f570c12f7",
        "counts": 5
      }
    ]
  }
}
```

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/)