New SectionURL NameUnderstanding-the-phone-existing-subscription-Field-in-the-Create-Contact-APITitleUnderstanding the phone_existing_subscription Field in the Create Contact APIOwnerGayatriArticle DetailsContentHelp ContentWhen updating contacts using the BayEngage Create Contact API (POST /customer), the phone_existing_subscription field provides a powerful way to manage the SMS subscription status for phone numbers that are already in your system. Its primary purpose is to prevent BayEngage from re-initiating the opt-in process, allowing you to preserve or retain a contact's current SMS subscription status.Core Function: Retaining Subscription Status By including phone_existing_subscription: "retain" in your API request, you instruct BayEngage to perform the following action: If the phone number provided in the API call already exists in your BayEngage account, its current SMS subscription status will be maintained. If the contact was subscribed, they will remain subscribed. If the contact was unsubscribed, they will remain unsubscribed. Example API Request Here is an example of a JSON payload for creating or updating a contact using this field. JSON Code { "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+1xxxxxxxx", "tags": ["tag1", "tag2"], // This field tells BayEngage to keep the existing SMS subscription status // for the phone number +1xxxxxxxx, if it already exists in the system. "phone_existing_subscription": "retain" } Key Scenarios and Outcomes This table summarizes the behavior based on different scenarios: Scenario phone_existing_subscription Value Resulting Action in BayEngage Phone number is new to BayEngage "retain" The field is ignored. A standard SMS opt-in confirmation is sent. Phone number already exists and is subscribed "retain" No new opt-in is sent. The contact remains subscribed to SMS. Phone number already exists but is unsubscribed "retain" No opt-in is sent. The contact's unsubscribed status is preserved. Any contact (new or existing) Field is not included in the API call The standard SMS opt-in process is triggered for the phone number. The phone_existing_subscription: "retain" field is a crucial tool for managing existing contacts without disrupting their current SMS subscription status. By using this optional parameter, you can confidently update contact information or sync your data from external systems, knowing that BayEngage will preserve the contact's original subscription choice.For more details on all available fields, please refer to the official Create Contact API Documentation.