Real-Time Contact Updating

We recommend regularly updating contacts via the Backend API (server-to-server) when some contact updates happen in your app's backend and frontend.

Let’s consider updating contacts in detail.

Using Backend API

Transfer contact data to eSputnik using the Add/update a contact API method.

The method creates a new or updates an existing contact in real time (synchronously). This means when you receive the 200 response you can be sure that contact data is already actualized in eSputnik.

For example, you can use the Add/update a contact method to collect data on subscription changes.

Features:

• One request allows you to add or update one contact.
• If a contact card with an identifier from the request already exists in eSputnik, it will be updated. A contact will be created with all additional data from the request if it hasn't existed.
• When updating a contact using Add/update a contact, the request updates only the fields it carries. Fields omitted from the request keep their current values.

Method type: POST. The description of the method, fields, and request body format are available here.

URL to send request: https://api.esputnik.com/api/v1/contact

Identical requests to Add/update a contact sent within one minute are treated as duplicates. Requests to Generate event v3 do not have this deduplication: identical event requests are processed separately. A request with a different payload is a different request.

If you send an Add/update a contact request with an existing contact's phone number but a new email address, the method creates a new contact by default instead of updating the existing one — email takes priority for matching. To deduplicate by phone instead, use the bulk Add/update contacts method with dedupeOn: sms in the request body.

If you send an event that starts a workflow for this contact, wait for the response confirming the contact was created before sending the event — otherwise the workflow can start before the contact ID exists, and the sending block will fail with an error. As an extra safeguard, add the Timer and Get contact blocks at the start of the workflow.

API Use Case for Web-to-App Project

1. A user has completed onboarding on the site (answered the questionnaire questions).

2. The Add/update a contact API method creates a contact profile with data collected on the site and external ID as the main identifier.

3. The user has downloaded and opened the mobile app.

4. SDK creates the anonymous contact with the Device ID.

5. The user logged in to the app.

6. The SetUserAttributes request with the external ID updates the existing contact with the Device ID and push token and deletes the anonymous contact.

Updating a Contact by ID

Update a contact identifies the contact by the ID in the request URL. The dedupeOn parameter isn't used here — it belongs to the Add/update contacts bulk API method (v1/contacts).

This method also restores a deleted contact: the profile returns from Deleted with the values from the request.