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 Reteno 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 Reteno.

Features:

• One request allows you to add or update one contact.
• If a contact card with an identifier from the request already exists in Reteno, it will be updated. A contact will be created with all additional data from the request if it hasn't existed.
• The request must contain either the channels array or externalCustomerId. A request with externalCustomerId only, without any channels, is accepted: if a contact with that external ID already exists, it's updated; if it doesn't, a new contact is created without any channel. This applies to the single-contact resource only — the bulk Add/update contacts resource (v1/contacts) still requires the channels array. An update sent by contactId without channels returns the Contact does not contain any channel error.
• To add the contact to a static segment right away, pass the segment name in groups[].name. If no segment with this name exists, it's created.
• 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.reteno.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. A repeated request gets the 409 Duplicated request response without the contact ID. To get the ID, find the contact by externalCustomerId with Search contacts.

A client-side timeout doesn't mean the data wasn't saved: the request can reach the system and be processed after the client stops waiting for the response. Repeating it is safe — if the first request was processed, deduplication prevents the contact from being created twice, and the response is 409 Duplicated request.

Deduplication looks at the request body, not at how the first attempt ended. If a malformed body was rejected with 400, sending the same body again within a minute returns 409 Duplicated request and hides the original error. Read the response to the first attempt, not to the repeats.

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.

📘

You need to obtain an API key and use it for authentication. This key provides access to your Reteno account, so make sure to keep it secure and never expose it publicly or through insecure communication channels.

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

The request needs only the fields you want to change: channels is optional, and fields omitted from the request keep their current values.

This method also restores a deleted contact: the profile returns from Deleted with the values from the request. A contact deleted with erase=true isn't restored: the request creates a new contact with a new ID and only the data from the request.