This API endpoint enables registration of customers in real-time, once a customer is assigned a persistent Customer ID. By doing this, data about this customer can be accumulated right away.

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

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.

Error Handling

Input Errors:

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

Fields:

Field	Data Type	Required	Description
`CustomerId`	String	Yes	Unique identifier for the customer as registered in clients systems.
`Attributes`	Array	No	List of customer attributes to update or insert.
`CallbackUrl`	String	No	Optional callback URL for post-processing.

Attributes Array's Fields:

Field	Data Type	Required	Description
`Attributes`	Array	No	List of customer attributes to update or insert.
`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.

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

Sample Request

{
    "CustomerId": "0192837821",
    "Attributes": [
      {
        "RealFieldName": "LIFECYCLESTAGE",
        "Value": "Registered Only"
      },
      {
        "RealFieldName": "COUNTRY",
        "Value": "US"
      }
    ],
    "CallbackUrl": "https://tenantname.requestcatcher.com/test"
  }