---
title: "Add/update a contact"
method: POST
path: "/api/v1/contact"
tags: ["Contacts"]
---

# Add/update a contact

`POST /api/v1/contact`

Creates or updates contacts in real-time. <a href="https://docs.esputnik.com/docs/adding-new-users">Details ></a>.<br/>The guide on bulk contact uploading and updating is available <a href="https://docs.esputnik.com/docs/uploading-file-with-user-profile-data">at the link</a>.<br/><a href="https://docs.esputnik.com/reference/addupdate-a-contact-request-example">Request example</a>.

## Request body

- Contact — Contact for subscription.
  - `firstName` string — Contact’s first name. <a href="https://docs.esputnik.com/docs/contact-fields#first-name">Read more...</a>
  - `lastName` string — Contact’s last name. <a href="https://docs.esputnik.com/docs/contact-fields#last-name">Read more...</a>
  - `channels` Channel[] — The list of media channels: • <a href="https://docs.esputnik.com/docs/contact-fields#email">Email</a> • <a href="https://docs.esputnik.com/docs/contact-fields#phone-number">Phone number (SMS, Viber)</a> • <a href="https://docs.esputnik.com/docs/contact-fields#applications-telegram-mob-push-web-push">Applications (App Inbox, Telegram and In-App messages), Mobile Push</a>
    - `type` 'email' | 'sms' | 'viber' | 'mobilepush' | 'webpush' | 'appinbox' | 'widget' | 'inapp, telegrambot' — Channel type
    - `value` string — Email address, phone number or push token
    - `device` Device — The data about the contact's device. Used together with the &quot;mobilepush&quot; channel type.
      - `appId` string — Application ID
      - `deviceModel` string — Device model
      - `os` string — Device OS
      - `locale` string — Locale (en_UK, ru_UA, ua_UA).
      - `clientVersion` 'native' | 'esputnik-1' — SDK version
      - `appVersion` string — Mobile app version
      - `active` boolean — Token activity flag
    - `webPushSubscription` WebPushSubscription — The data about the web push subscription. Used together with the &quot;webpush&quot; channel type.
      - `appId` integer
      - `userAgent` string
      - `userAgentVersion` string
      - `userAgentLanguage` string
      - `os` string
      - `ip` string
      - `subscriptionPage` string
      - `swActiveVersion` string
    - `appUuid` string — App UUID for telegram bot channel
  - `address` Address — Contact's full address. <a href="https://docs.esputnik.com/docs/contact-fields#address">Read more...</a>
    - `region` string — Region
    - `town` string — City
    - `address` string — Address
    - `postcode` string — Postal/ZIP code
    - `countryCode` string, nullable — Country code (ISO-3166-1 alpha-2, UK and ZZ allowed). Case-insensitive. Stored as UPPERCASE. Invalid → null.
  - `fields` ContactField[] — Values of the additional fields for a contact. <a href="https://docs.esputnik.com/docs/contact-fields#additional-fields-format-filling">Read more...</a>
    - `id` integer — Additional field ID.<br/>You can get the value using the <i>/v1/addressbooks GET</i> method.
    - `value` string — The value of an additional field.
  - `addressBookId` integer — The list of additional contact fields. <a href="https://docs.esputnik.com/reference/getaddressbooks-1">Read more...</a>
  - `id` integer — A field containing the internal contact ID in our system. <a href="https://docs.esputnik.com/docs/contact-fields#contact-id">Read more...</a>
  - `externalCustomerId` string — A field containing the internal contact ID in your system. <a href="https://docs.esputnik.com/docs/contact-fields#external-id">Read more...</a>
  - `groups` GroupDto[] — The list of static segments where the contact is present. Used only when receiving contacts. <a href="https://docs.esputnik.com/docs/segments">Read more...</a>
    - `id` integer — Segment ID
    - `name` string
    - `type` string — Possible values: Static - simple static segment (list), Dynamic - conditional segment, Combined - composite segment.
  - `languageCode` string — Language code for the contact. <a href="https://docs.esputnik.com/docs/contact-fields#language">Read more...</a>
  - `timeZone` string — The contact's time zone. <a href="https://docs.esputnik.com/docs/contact-fields#time-zone">Read more...</a>
  - `marketId` string — Customer market/region identifier. Optional parameter. Up to 64 characters. Allowed symbols: [a-zA-Z0-9-_]

## Response `200`

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `405` — Method not allowed
- `409` — Conflict:<br><ul><li>Repeated request within 1 minute.</li></ul>
- `415` — Unsupported media type
- `429` — Too many requests:<br><ul><li>More than 200 requests per 1 second.</li></ul>

---

[API](https://skmtc.net/esputnik/apis/esputnik-com.md) · [All operations](https://skmtc.net/esputnik/apis/esputnik-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esputnik/esputnik-com/versions/1c4afd7ba72a/schema)