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

# Subscribe a contact

`POST /api/v1/contact/subscribe`

The method is used for <a href="https://docs.esputnik.com/reference/integrating-subscription-form-via-api">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. <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-_]
  - `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.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)