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.
• A request updates only the fields it carries. Fields the request omits keep their current values — a later request that sends phone alone doesn't clear the email saved at registration.

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

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. It applies to identical requests sent within one minute and works only for the Add/update a contact resource (v1/contact). Sending requests with different data for the same contact doesn't trigger it, and the Generate event resource has no such deduplication: identical events are all accepted and stored.

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.

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 and a phone number and the next request passes only the phone number, the email is kept. To clear a contact's email channel when updating by externalCustomerId or phone, mark email in contactFields for the update and omit it from the channels array.

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.