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

# Add/update contacts

`POST /api/v1/contacts`

## Request

- Base URL: `https://yespo.io` (the document declares no server; this is the origin it was published from)
- URL: `https://yespo.io/api/v1/contacts`
- Auth: HTTP basic

The method adds new contacts and updates existing contacts.

## 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. The following rules apply to character usage: <br> - Max length: 40 symbols. <br>- Letters from any alphabet are allowed (Unicode characters). <br>- Three words longer than 3 characters and three words with a maximum of 3 characters are allowed. <br>- Up to 3 digits are allowed. <br>- Special characters are not allowed, except for: <br>-- Apostrophes ''ʼ`´ʹʻʽʾʿˈˊˮʹ΄՚᾽᾿'‛′‵Ꞌꞌ＇ (only inside words) <br>-- Hyphen - (only inside words) <br>-- One dot at the end of words having max 3 characters. Example: Jr. <br>- Names consisting only of numbers and special characters are not allowed
    - `lastName` string: Contact’s last name. The following rules apply to character usage: <br> - Max length: 40 symbols. <br>- Letters from any alphabet are allowed (Unicode characters). <br>- Three words longer than 3 characters and three words with a maximum of 3 characters are allowed. <br>- Up to 3 digits are allowed. <br>- Special characters are not allowed, except for: <br>-- Apostrophes ''ʼ`´ʹʻʽʾʿˈˊˮʹ΄՚᾽᾿'‛′‵Ꞌꞌ＇ (only inside words) <br>-- Hyphen - (only inside words) <br>-- One dot at the end of words having max 3 characters. Example: Jr. <br>- Names consisting only of numbers and special characters are not allowed
    - `channels` Channel[]: The list of media channels
      - `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
      - `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
      - `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: You can get the info about catalogs using the <i>/v1/addressbooks GET</i> method
    - `id` integer: Contact ID
    - `externalCustomerId` string: External contact id
    - `contactKey` string: Contact's key
    - `groups` GroupDto[]: The list of the static segments where the contact is present. Used only when receiving contacts.
      - `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
    - `timeZone` string: The contact's time zone. See <a href='https://en.wikipedia.org/wiki/List_of_tz_database_time_zones'>TZ database name</a>.
    - `marketId` string: Market ID. Optional parameter. Up to 64 characters. Allowed: [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.dev/yespo/apis/yespo-api.md) · [All operations](https://skmtc.dev/yespo/apis/yespo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yespo/apis/yespo-api/revisions/b662f92b6c40?raw)