--- title: User Identity Persistence in Requests slug: engine-api/user-identity-persist description: How to identify new and returning visitors in Monetate Engine API requests and responses using monetateId and deviceId image: https://archbee-image-uploads.s3.amazonaws.com/ceIfEvQHzQk1IVxoRWUh7/K9eTL4jKm7UQINb6zNziJ-20250912-181225.png docTags: createdAt: 2024-05-09T14:31:08.684Z --- Monetate identifies anonymous visitors and tracks behavior via a `monetateId`. This ID is generated on the first request to the platform if it's not already present and identifies a unique device or browser. In a traditional [Monetate JavaScript API](docId\:zcx_p3d6ND2Rr5bJLOyUG) implementation, `monetateId` is set as a first-party cookie, `mt.v`. It persists for future site visits. For Engine API implementations, however, Monetate generates a `monetateId` if no identifier is passed in the request. Because Monetate has no way to set the `mt.v` cookie in an Engine API implementation, the requesting application is responsible for keeping track of the `monetateId` by setting the cookie or otherwise storing or maintaining the persistence of the value by other means unique to your application. If a device ID is available that can uniquely identify the customer's device across requests, then you can alternatively include `deviceId` in all Engine API requests. This value then acts as a unique identifier and allows Monetate to track visitor behavior throughout the current session and across future sessions. To summarize user identity persistence options for Engine API clients: - `monetateId` — Can be used for an application and must stored in a variable on your end. - `deviceId` — Can be used as an alternative to `monetateId` to identify the customer's device across requests that doesn't need to be stored. This value acts as a unique identifier and allows Monetate to track customer behavior throughout the current session as well as across future sessions. :::hint{type="info"} Whether you use `monetateId` or `deviceId` to identify the customer, you must include it in all requests for both current and future sessions. ::: ## Hybrid Implementations For [hybrid implementations](docId\:ZFxS45Ymf6aIcWwKKgXcC), ensure that you do the following: - If a `monetateId` exists in the `mt.v` cookie, then you must pass it in all Engine API requests. - If no existing `monetateId` is present in an `mt.v` cookie, then you must ensure that the `monetateId` generated by the initial Engine API request is set as a first-party cookie named `mt.v`, which is case-sensitive. These user identity measures allow Monetate to reconcile information collected by both the Engine API and the [Monetate tag](docId\:zcx_p3d6ND2Rr5bJLOyUG) into a single unified session. :::hint{type="warning"} You must take these measures to ensure the seamless functioning and optimal performance of your hybrid implementation. Failure to do so can result in a variety of issues, including disconnected user experiences and inaccurate data tracking. ::: Contact your dedicated Customer Success Manager (CSM) if you need assistance with these steps. ## monetateId Example Requests ### New Visitor Request This example of a New Visitor request has no `monetateId`. In the response Monetate includes it. :::CodeblockTabs New Visitor Request Without monetateId ```json { "channel": "a-12345678/d/example.test", "events": [ { "eventType": "monetate:decision:DecisionRequest", "requestId": "11111" }, { "eventType": "monetate:context:IpAddress", "ipAddress": "127.0.0.1" }, { "eventType": "monetate:context:PageView", "url": "https://www.example.test/path" } ] } ``` New Visitor Response ```json { "meta": { "code": 200, "monetateId": "5.977810341.1521134874631" }, "data": { "responses": [ { "requestId": "11111", "actions": [ { "data": { "example": "json" }, "actionType": "monetate:action:OmniJson" } ] } ] } } ``` ::: ### Returning Visitor Request A `monetateId` is included in this example Returning Visitor request, which is mirrored in the response. :::CodeblockTabs Returning Visitor Request Without monetateId ```json { "channel": "a-12345678/d/example.test", "monetateId": "5.977810341.1521134874631", "events": [ { "eventType": "monetate:decision:DecisionRequest", "requestId": "11111" }, { "eventType": "monetate:context:IpAddress", "ipAddress": "127.0.0.1" }, { "eventType": "monetate:context:PageView", "url": "https://www.example.test/path" } ] } ``` Returning Visitor Response ```json { "meta": { "code": 200 }, "data": { "responses": [ { "requestId": "11111", "actions": [ { "data": { "example": "json" }, "actionType": "monetate:action:OmniJson" } ] } ] } } ``` ::: ## deviceId Sample Requests ### New Visitor Request In this example New Visitor request, `deviceId` is passed instead of `monetateId`. In this scenario, it's a New Visitor request because Monetate hasn't received this `deviceId` before. In the response, Monetate doesn't include the `deviceId` but instead returns `monetateId`, which can be ignored in this instance. :::CodeblockTabs New Visitor Request with deviceId ```json { "channel": "a-12345678/d/example.test", "deviceId": "39hu7lgj05454nj5t4", "events": [ { "eventType": "monetate:decision:DecisionRequest", "requestId": "11111" }, { "eventType": "monetate:context:IpAddress", "ipAddress": "127.0.0.1" }, { "eventType": "monetate:context:PageView", "url": "https://www.example.test/path" } ] } ``` New Visitor Response with monetateId ```json { "meta": { "code": 200, "monetateId": "5.977810341.1521134874631" }, "data": { "responses": [ { "requestId": "11111", "actions": [ { "data": { "example": "json" }, "actionType": "monetate:action:OmniJson" } ] } ] } } ``` ::: ### Returning Visitor Request When the same `deviceId` is sent again, Monetate recognizes it and classifies it as a Returning Visitor. As in the response in the New Visitor request that contained a `deviceId` value, Monetate doesn't include the `deviceId` but instead returns `monetateId`. :::CodeblockTabs Returning Visitor Request with deviceId ```json { "channel": "a-12345678/d/example.test", "deviceId": "39hu7lgj05454nj5t4", "events": [ { "eventType": "monetate:decision:DecisionRequest", "requestId": "11111" }, { "eventType": "monetate:context:IpAddress", "ipAddress": "127.0.0.1" }, { "eventType": "monetate:context:PageView", "url": "https://www.example.test/path" } ] } ``` Returning Visitor Response with monetateId ```json { "meta": { "code": 200, "monetateId": "5.977810341.1521134874631" }, "data": { "responses": [ { "requestId": "11111", "actions": [ { "data": { "example": "json" }, "actionType": "monetate:action:OmniJson" } ] } ] } } ``` ::: ## Custom Variables for New or Returning Visitors You can pass `deviceId` and a [custom variable](docId\:qWXOawFdBWNX4Zarj-hAh) in a request to let Monetate know that this customer is either a new or returning visitor. :::CodeblockTabs Request with deviceId and Custom Variable ```json { "channel": "a-12345678/d/example.test", "deviceId": "39hu7lgj05454nj5t4", "events": [ { "eventType": "monetate:decision:DecisionRequest", "requestId": "11111" }, { "eventType": "monetate:context:IpAddress", "ipAddress": "127.0.0.1" }, { "eventType": "monetate:context:CustomVariables", "customVariables": [ { "variable": "Returning_Visitor", "value": "True" } ] }, { "eventType": "monetate:context:PageView", "url": "https://www.example.test/path" } ] } ``` ::: When you first send `deviceId`, the Engine API classifies the customer as new. When you use custom variables, you send the custom variable in addition to `deviceId` to ensure that new visitors are targeted. ### Targeting New and Returning Visitors with deviceId and Custom Variables Use the **Custom variable visitors** option in the [Landing target type](https://docs.monetate.com/docs/types-of-who-targets#landing-page-targets) to target new and returning visitors when configuring the WHO settings of an experience. ![The 'Custom variable visitors' target for the WHO settings of an experience, with 'New\_Visitor' in the 'Variable name' field and 'True' as the variable value](https://dyzz9obi78pm5.cloudfront.net/app/image/id/6442e3d228ea17508c7f3af4/n/experiences-who-landing-custom-variable-visitors-new-visitors-variable.png) You can also use the **New visitors** and **Returning visitors** options in the Landing target type instead of custom variables. ![Callout of the 'New visitors' and 'Returning visitors' options on the Landing target type panel of the WHO settings of an experience](https://dyzz9obi78pm5.cloudfront.net/app/image/id/6442e3250d3a9c1b9b6dd794/n/experiences-who-landing-new-visitors-returning-visitors.png) ## Identifying Known Customers Included in a Customer Dataset You can provide a `customerId` for logged-in customers of your application. This ID identifies someone in, for example, a loyalty program. It's associated with the identified device and allows you to use your own data that you've uploaded to Monetate in a [customer dataset](https://docs.monetate.com/docs/customer-data) for targeting and context. ::::ExpandableHeading ### For Customer Datasets :::hint{type="danger"} This content is only for clients with **Product Data** and **Customer Data** options in the **DATASETS** menu in the top navigation bar of the Monetate platform. If no menu options appear when you click **DATASETS**, then this content doesn't apply to your account. Instead, see [For Customer Attributes Datasets](docId:7M254uPWksja-XLMmy6m4). ::: You must send `monetateId` or `deviceId` with each request. :::hint{type="warning"} You cannot use `customerId` in lieu of `monetateId` or `deviceId`. ::: :::CodeblockTabs Request with monetateId and customerId ```json { "channel": "a-1d121c07/p/monetate-api.myshopify.com", "monetateId": "5.1824559023.1570975471014", "customerId": "123abc", "events": [ { ... ``` ::: :::: ::::ExpandableHeading ### For Customer Attributes Datasets :::hint{type="danger"} This content is only for clients with the one-click **DATASETS** option in the top navigation bar of the Monetate platform. If you click **DATASETS** and see **Product Data** and **Customer Data** listed as menu options, then this content doesn't apply to your account. Instead, see [For Customer Datasets](docId:7M254uPWksja-XLMmy6m4). ::: If you have a [Customer View](https://docs.monetate.com/docs/configure-customer-view) enabled and have a different type of customer identifier, then continue to send `customerId` for the Customer View and send the Customer Attribute dataset's [Identifier Name](https://docs.monetate.com/docs/customer-attributes-dataset-details-page#setting-an-identifier-name), which you can find on the [Customer Attributes view of the Datasets list page](https://docs.monetate.com/docs/datasets-list-page#customer-attributes), via a custom variable. You don't need to add the custom variable value for the Identifier Name to an experience. :::CodeblockTabs Request with customerId and Identifier Name in Custom Variable ```json { "channel": "a-1d121c07/p/monetate-api.myshopify.com", "customerId": "123abc", "events": [ { "eventType": "monetate:context:CustomVariables", "customVariables": [ { "variable": "LoyaltyId", "value": "1234" } ] } ] } ``` ::: :::: ## Using Customer View with Engine API It's possible to have a single view of a customer across mobile, desktop, and apps as long as the `customerId` is the same. Doing so stitches together the behavioral data for the customer for the corresponding behavioral targets supported by a [Customer View](https://docs.monetate.com/docs/configure-customer-view). This setup works in Web experiences by matching on the `customerId`, which then guarantees that Monetate serves the same experience for customer A. To have this same matching to happen in your Omnichannel experiences, then you must contact the Services team to set up an [ID Collector](https://docs.monetate.com/docs/create-an-id-collector). If your account already has an ID Collector set up for Web experiences, then provide the name so that it can be copied to your app accounts. Client-side developers must take the following steps: 1. [Create an Omnichannel experience](https://docs.monetate.com/docs/create-an-omnichannel-experience) with the [Omni JSON](https://docs.monetate.com/docs/omnichannel-experiences-available-action-types#omni-json) action matching the desktop experience to ensure that the customer sees the same visual change. 2. Pass a `customerId` in the request along with all relevant or identical target information as context. The Engine API responds to the request with the eligible experiences.