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

# Subscribe a contact

`POST /api/v1/contact/subscribe`

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

The method is used for <a href="${v1contactsubscribe.post.link}">the integration of subscription forms</a>.<br/>If a contact does not exist, it is created with the non-confirmed email.<br/>If a contact exists, the contact fields are updated (except existing media channels).<br/>New contacts are created with a <b>not confirmed</b> status.<br/>

## Request body

- SubscribeContact: The method for double opt-in implementation. A created contact is unconfirmed.<br/> It is impossible to send bulk emails to such contacts until they confirm their subscription; however, they are available for receiving important trigger messages.<br/> An event will be automatically generated after this method is called.<br/> Sending a confirmation email can be implemented using the mechanism of events and campaigns.<br/> When clicking the link in the letter, a contact becomes confirmed and available for bulk emails sending.
  - `contact` Contact, required: Contact for subscription.
    - `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-_]
  - `groups` string[]: The list of segment names where a new/updated contact will be added.
  - `subscriptions` string[]: Subscription categories added for a contact.
  - `formType` string: The subscription form name. It allows you to use several independent subscription forms.<br/> All characters are acceptable, except: < ; ’ \ / | " ` ' ^ ? ! , >

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