This API endpoint enables registration of one or more customers in real-time, once a customer is assigned a persistent Customer ID. It is possible to send a single customer or up to 1000 customers in the same API call. By doing this, data about these customers can be accumulated right away. If Optimove does not recognize the provided Customer ID, we will use it to register the new customer.

If a customer is being registered immediately, they will retain the values that were reported upon registration or updated since then. When new, richer information is reported in batch data delivered to Optimove, it will update this customer data and attributes.

🚧
Note - This functionality is being gradually rolled out to clients, so it might not be available in some of the environments.

Rate Limit

This endpoint is subject to the general API rate limit of 50 requests per 10 seconds. Learn more about handling rate limits.

⚠️
Important: Data Processing & Campaign Timing
Please be aware of a daily processing cycle. Data updates sent via the API during this processing window will only be reflected after the next daily cycle completes.
Crucially, if you need to update data for a campaign launching the following day, you must send those updates_before_ the daily process begins.

Notes

Batch Limit: You can update up to 1000 customers in a single API call.
Size Limit: The maximum allowed payload size per call is 0.5 MB.
Attribute Limit: There is no limit on the number of attributes you can update per customer, provided the total request payload remains under the 0.5 MB size limit.
CustomerID is expected to be persistent in representing the same customer in future events and batch data deliveries.
Attributes are identified by their RealFieldName values. You can retrieve all available customer attribute names and a description of each using the GetCustomerAttributeList function or by accessing the Customer Attributes list in Optimove’s interface and exporting the list.
When updating an attribute, the attribute values supplied in this call overwrite any previous values in the database.
This endpoint is currently not supported in environments where ID mapping is applied.
You can send a request with only CustomerId and no attributes. In that case, the customer will be registered without any additional attributes. To do this, you must send Attributes as an empty array ([]), not null, because null attributes are not accepted.

Request Structure

This payload is a JSON object with two top-level properties: an array called Customers and a string called CallBackUrl. The Customers array contains customer objects, each with a CustomerId field and an Attributes array, where each element is an object composed of RealFieldName and Value string fields. The CallBackUrl field defines the URL endpoint to which the system will send an asynchronous callback after processing the request.

General Fields

Field	Data Type	Required	Description
`Customers`	String	Yes	An array of objects contain all customers in this request.
`CallbackUrl`	String	No	Optional callback URL for post-processing. This will capture the status messages.

Customer Object Fields:

Field	Data Type	Required	Description
`CustomerId`	String	Yes	Unique identifier for the customer as registered in clients systems.
`Attributes`	Array	No	An array of objects that describe each attribute update.

Attribute Object Fields:

Field	Data Type	Required	Description
`RealFieldName`	String	Yes	Name of the field being updated.
`Value`	String	No	Value to be assigned to the field. If NULL value is provided any existing values will be nullified.

Sample Request

{
  "Customers": [
    {
      "CustomerId": "hello2",
      "Attributes": [
        {
          "RealFieldName": "BALANCE",
          "Value": "12"
        },
        {
          "RealFieldName": "COUNTRY",
          "Value": "IL"
        }
      ]
    },
    {
      "CustomerId": "Carlinhos",
      "Attributes": [
        {
          "RealFieldName": "LIFECYCLESTAGE",
          "Value": "New"
        },
        {
          "RealFieldName": "COUNTRY",
          "Value": "UK"
        }
      ]
    }
  ],
  "CallbackUrl": "https://tenantname.requestcatcher.com/test"
}

Error Handling

Input Errors:

The following error types will appear in "errors" array in the response to the API request.

Errors while using this endpoint typically occur due to invalid input or missing required field.

Example for reference:

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-1885aa03207df32c3c6bd9ed6f57838c-74dd6db0e400caa4-00",
    "errors": {
        "CustomerID": [
            "The CustomerID field is required."
        ]
    }
}

Callback URL Errors:

If a Callback URL was defined, you would receive the following response to the Webhook up to 1 minute after the call (Currently, all rejections are marked as CUSTOMER_VALIDATION_REJECTION):

Empty attribute list is not allowed - the payload of an existing customer contained an empty list of attributes updates
Attribute specific rejections:
1. Invalid attribute name - {RealFieldName} - payload contains an attribute that is not part of the current database configuration.
2. Updates for attribute {RealFieldName} are not allowed - payload contains an attribute that is forbidden to be updated using this process. Currently, this includes INTERNAL attributes, as well as attributes from the list of restricted attributes.
3. Unable to convert {RealFieldName} value to type {ATTRIBUTE_TYPE} - payload contains an attribute value of which does not correspond to its data type from the database configuration.

Example for reference (to callback URL):

{
  "traceId": "b66ca444-c10b-4587-8dfb-95fd37c86291", 
  "reason": "CUSTOMER_VALIDATION_REJECTION", 
  "message": "Unable to convert 'NumberOfBetDays' value to type 'bigint'"
}

Beware! Rejections are not stored and are lost if not sent to a Callback URL immediately