---
title: "List your contacts"
method: GET
path: "/contacts"
tags: ["contacts"]
---

# List your contacts

`GET /contacts`

Retrieves your list of contacts (yours and those shared with you). The maximum number of rows returned is set by the parameter <em>limit_count</em> (limited to 500 rows).
All parameters are optional. If the \"search\" parameter is filled, results are sorted by relevance (according to how good the match is).
Note: If a contact has an emoji in their `firstname`, `lastname`, and/or `company`, it will not be displayed in the response body.

**Permission:** `Contacts Read` required.

**Monitoring:** No impact.

## Query parameters

- `pagination` string
- `alphabetical_order` string
- `search` string
- `limit_count` integer
- `limit_offset` integer

## Response `200`

Successful operation — the contact list is returned.

- ContactList
  - `list_count` integer
  - `user_id` integer
  - `team_id` integer
  - `limit_count_setted` integer
  - `limit_offset_setted` integer
  - `total_contact_count` integer — This field is not used anymore.
  - `contact_list_count` integer
  - `contact_list` ContactFull[]
    - `contact_id` integer
    - `is_shared` boolean
    - `im_owner` boolean
    - `social_service` string, nullable
    - `social_service_id` string, nullable
    - `social_profile_url` string, nullable
    - `social_data` string, nullable
    - `firstname` string
    - `lastname` string
    - `company` string
    - `concat_name` string
    - `color` string
    - `initial` string
    - `profile_picture` string
    - `creation_date` string, date-time
    - `numbers` NumberLightWithFormat[]
      - `number` integer
      - `type` string
      - `format` FormatNumber
        - `raw` integer
        - `country_code` string
        - `country` string
        - `e164` string
        - `international` string
        - `international_alt` string
        - `national` string
        - `national_alt` string
        - `rfc3966` string
        - `is_short_code` boolean

## Other responses

- `204` — No contacts found matching your criteria.
- `400` — Invalid query parameter supplied.
- `401` — Unauthorized — missing or invalid API token, or missing `Contacts Read` permission.
- `500` — Internal server error.

---

[API](https://skmtc.net/ringover/apis/ringover-public-api.md) · [All operations](https://skmtc.net/ringover/apis/ringover-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ringover/ringover-public-api/revisions/9da73dd2f99e/schema)