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

# Add/update a contact

`POST /api/v1/contact`

## 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/contact`
- Auth: HTTP basic

The method is used to add a new or update an existing contact. The ID field is ignored.<br>To learn more about importing or updating contacts and their additional fields, read <a href="${v1contact.post.link}">Importing historical data</a>.

## Request body

- ContactCreateRequestSchema
  - `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` ContactWriteChannel[]: The list of media channels
    - `type` 'email' | 'sms' | 'mobilepush' | 'webpush': 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
  - `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-_]

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