---
title: "Create, update, or retrieve a contact"
method: POST
path: "/v1/projects/{project_id}/contacts"
tags: ["Contact"]
---

# Create, update, or retrieve a contact

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

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/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`)

Retrieves OR creates and possibly updates a contact by name or phone number.

 If a phone number is provided, by default, Telerivet will search for an existing contact with that phone number (including suffix matches to allow finding contacts with phone numbers in a different format). If a phone number is not provided but a name is provided, Telerivet will search for a contact with that exact name (case insensitive). This behavior can be modified by setting the `lookup_key` parameter to look up a contact by another field, including a custom variable.

 If no existing contact is found, a new contact will be created.

 Then that contact will be updated with any parameters provided (`name`, `phone_number`, `vars`, `default_route_id`, `send_blocked`, `add_group_ids`, `remove_group_ids`).

## Path parameters

- `project_id` string, required

## Request body

- object
  - `name` string: Name of the contact
  - `phone_number` string: Phone number of the contact
  - `lookup_key` 'phone_number' | 'name' | '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.'.
  - `send_blocked` boolean: True if Telerivet is blocked from sending messages to this contact
  - `default_route_id` string: ID of the route to use by default to send messages to this contact
  - `add_group_ids` string: ID of one or more groups to add this contact as a member (max 20)
  - `id` string: ID of an existing contact (only used if `lookup_key` is 'id')
  - `remove_group_ids` string: ID of one or more groups to remove this contact as a member (max 20)
  - `vars` object: Custom variables and values to update on the contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

## Response `200`

Successful response

- Contact: A contact represents a person or other entity that can be communicated with via phone number or other messaging channel within a project. Each contact has a name, phone number, and custom variables that can be used to personalize messages. Contacts can belong to one or more groups, and can be used as recipients for broadcasts, campaigns, and other messaging operations. Contacts can be imported or created individually via the API or web app. If the project's auto_create_contacts setting is enabled, a contact will be automatically created for each unique phone number that a message is sent to or received from.
  - `id` string: ID of the contact
  - `name` string: Name of the contact
  - `phone_number` string: Phone number of the contact
  - `time_created` integer: Time the contact was added in Telerivet
  - `time_updated` integer: Time the contact was last updated in Telerivet
  - `send_blocked` boolean: True if Telerivet is blocked from sending messages to this contact
  - `conversation_status` 'closed' | 'active' | 'handled': Current status of the conversation with this contact
  - `last_message_time` integer, nullable: Last time the contact sent or received a message (null if no messages have been sent or received)
  - `last_incoming_message_time` integer, nullable: Last time a message was received from this contact
  - `last_outgoing_message_time` integer, nullable: Last time a message was sent to this contact
  - `message_count` integer: Total number of non-deleted messages sent to or received from this contact
  - `incoming_message_count` integer: Number of messages received from this contact
  - `outgoing_message_count` integer: Number of messages sent to this contact
  - `last_message_id` string: ID of the last message sent to or received from this contact (null if no messages have been sent or received)
  - `default_route_id` string: ID of the basic route (phone) or custom route that Telerivet will use by default to send messages to this contact (null if using project default route)
  - `group_ids` string[]: List of IDs of groups that this contact belongs to
  - `vars` object: Custom variables stored for this contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `project_id` string: ID of the project this contact belongs to
  - `url` string: URL to this contact in the Telerivet web app

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