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

# Add/update contacts

`POST /api/v1/contacts`

The method adds new contacts and updates existing contacts. Asynchronous processing is used; requests may be handled in a different order or concurrently.

## Request body

- ContactsBulkUpdate — Multiple adding/updating contacts.
  - `contacts` Contact[], required — The list of contacts that will be added or updated (max. 3000).<br/>If this array of objects contains externalCustomerId, the search uses externalCustomerId and ignores dedupeOn.
    - `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-_]
  - `dedupeOn` 'email' | 'sms' | 'push' | 'email_or_sms' | 'id' | 'externalCustomerId' | 'fieldId', required — The field for determining the contact uniqueness. <b>Important</b> the field set as <b>dedupeOn</b> will not be updated
  - `fieldId` integer — The field for determining the contact uniqueness. This field is taken into account when dedupeOnProperty has the fieldId value.
  - `contactFields` string[] — The list of contacts’ fields to be updated. All the contact fields will be updated if this parameter is not specified. The fields will be updated with the ‘null’ value if no data for updating is transmitted.
  - `customFieldsIDs` integer[] — The list of the custom field IDs to be updated.<br> The custom fields are updated if their IDs are in this list.<br> This field is required when a contact is updated
  - `groupNames` string[] — The list of the segment names where the new/updated contacts will be added to.
  - `groupNamesExclude` string[] — The list of the segment names where the new/updated contacts will be excluded from.
  - `restoreDeleted` boolean — Choose either to restore the previously deleted contacts or not.
  - `eventKeyForNewContacts` string — The event type identification key. An event of corresponding type is generated for each contact. <br> If the system does not have an event type with such a key, a new event type is created. <br> All characters are allowed, except < ; ’ \ / | " ` ' ^ ? ! , > <br> Max length: 100 symbols

## Response `200`

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `405` — Method not allowed
- `415` — Unsupported media type
- `429` — Too many requests: More than 200 requests per 1 second

---

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