---
title: "Retrieve or create contacts"
method: POST
path: "/contacts"
tags: ["contacts"]
---

# Retrieve or create contacts

`POST /contacts`

This endpoint serves two purposes depending on the request body: send a <b>contact_filter</b> object to retrieve contacts (yours and those shared with you), or a <b>contact_creation</b> object to create new ones. Only one parameter must be sent.
When creating contacts, each contact is automatically assigned to the user associated with the API key used for the request. You can create up to 50 contacts at once.
When retrieving contacts, the maximum number of contacts returned is defined by the <em>limit_count</em> variable (limited to 500 contacts).
If the \"search\" parameter is filled, results are sorted by relevance (based on how well they match).
Note: If you create a contact with an emoji in the `firstname`, `lastname`, or `company` fields, it will work but the emoji will not be displayed in the response body when retrieving the contact.

**Permission:** `Contacts Write` required when creating contacts. `Contacts Read` is sufficient for retrieval.

**Monitoring:** No impact.

## Request body

- union
  - ContactFilter
    - `pagination` string, nullable — [Deprecated] The character sequence assigned to pages in address book. Possible values are: 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '#' for any digit and '.' for any other characters. An empty value disables pagination. The pagination is based on the lastname by default, you can paginate by firstname or company name by combining the 'pagination' and 'alphabetical_order' fields.
    - `alphabetical_order` string, nullable — [Deprecated] Alphabetical order impacts the pagination value. Possible values are : FirstnameLastnameCompanyDESC, FirstnameLastnameCompanyASC, LastnameFirstnameCompanyDESC, LastnameFirstnameCompanyASC, CompanyFirstnameLastnameDESC, CompanyFirstnameLastnameASC ,CompanyLastnameFirstnameDESC, CompanyLastnameFirstnameASC. Values all respect the format 'Field1Field2Field3ORDER' where 'Field1' will be the field the pagination is based on and 'ORDER' the order of the result (Ascending or Descending)
    - `search` string, nullable — The keyword is used to search a specific contact. Index is based on firstname, lastname, company and phone number(s).
    - `limit_count` integer, nullable — Maximum number of results to return per page. Used for pagination. Maximum: 500.
    - `limit_offset` integer, nullable — Number of elements that will be ignored, used to create a pagination cursor
  - NewContactRequest
    - `contacts` NewContact[]
      - `firstname` string
      - `lastname` string
      - `company` string
      - `is_shared` boolean
      - `numbers` NewNumberContact[]
        - `number` integer — Phone number (E.164 format)
        - `type` 'home' | 'office' | 'mobile' | 'fax' | 'other'

## Response `200`

Successful operation — the filtered 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

- `201` — Contact(s) successfully created.
- `204` — No contacts found matching your filter criteria.
- `400` — Invalid request body — check your JSON payload structure.
- `401` — Unauthorized — missing or invalid API token, or missing `Contacts Write` permission (for creation).
- `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)