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.

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

📘

Note

If you send two consecutive requests for the same contact with an identical request body, the second one returns 429 Too Many Requests — this is a deduplication safeguard, separate from the general rate limit. Sending requests with different data for the same contact doesn't trigger it.

The safeguard covers identical requests sent within a minute and applies to the v1/contact resource only. Events sent to v2/event are not deduplicated: identical events are all accepted and all appear in the event history.

📘

Note

To clear a contact's email channel via v1/contact when identifying the contact by externalCustomerId or phone, list email in contactFields for the update and omit it from the channels array. You don't need to pass null values — the channel is removed as long as "contactFields": ["email"] is passed and email is absent from channels. The same approach works for the Add/update contacts resource.

📘

Note

A field that isn't passed in an update request doesn't erase the previously saved value. For example, if a contact was created with an email address and a phone number, and the next request passes only the phone number, the email address is kept.

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.