---
title: "Import contacts"
method: POST
path: "/v1/projects/{project_id}/import_contacts"
tags: ["Contact"]
---

# Import contacts

`POST /v1/projects/{project_id}/import_contacts`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/import_contacts`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Creates and/or updates up to 200 contacts in a single API call. When creating or updating a large number of contacts, this method is significantly faster than sending a separate API request for each contact.

 By default, if the phone number for any contact matches an existing contact, the existing contact will be updated with any information provided. This behavior can be modified by setting the `lookup_key` parameter to look up contacts by another field, including a custom variable.

 If any contact was not found matching the provided `lookup_key`, a new contact will be created.

## Path parameters

- `project_id` string, required

## Request body

- object
  - `contacts` object[], required: Array of up to 200 objects which may contain the properties `name` (string), `phone_number` (string), `vars` (object), and `send_blocked` (boolean). All properties are optional, unless used as a lookup key; however, either a `name` or `phone_number` property must be provided for new contacts.
    - `name` string: Contact name
    - `phone_number` string: Contact phone number
    - `vars` object: Custom variables
    - `send_blocked` boolean: Whether to block outgoing messages to this contact
  - `lookup_key` 'phone_number' | 'id' | 'vars.variable_name' | 'none': The field used to search for a matching contact, or 'none' to always create a new contact. To search by a custom variable, precede the variable name with 'vars.'.
  - `add_group_ids` string: ID of one or more groups to add these contacts as members (max 5)
  - `remove_group_ids` string: ID of one or more groups to remove these contacts as members (max 5)
  - `default_route_id` string: ID of the route to use by default to send messages to these contacts

## Response `200`

Successful response

- object
  - `contacts` object[]: List of objects representing each contact, with the same length and order as provided in the `contacts` parameter in the API request. Each object has a string `id` property.
    - `id` string, required: ID of the contact

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)