--- title: Request Decisions slug: engine-api/engine-api-request-decisions description: Path and body parameters and responses for a Monetate Engine API decision request POST image: https://archbee-image-uploads.s3.amazonaws.com/ceIfEvQHzQk1IVxoRWUh7/K9eTL4jKm7UQINb6zNziJ-20250912-181225.png docTags: createdAt: 2024-05-21T18:38:32.296Z --- { "id": "IyAxSwemiK_DfLDDzdOY3", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://engine.monetate.net/api/engine/v1/decide/{retailerShortname}", "name": "Request Decisions", "description": "Monetate Decision API\n", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "retailerShortname", "type": "string", "description": "Shortname of the retailer." } ], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "example": "{\n \"deviceId\": \"device id\",\n \"monetateId\": \"monetate id\",\n \"preview\": \"preview token\",\n \"customerId\": \"customer id\",\n \"events\": [\n {\n \"eventType\": \"Event\"\n }\n ]\n}\n", "description": "The request containing the events requiring decisioning.", "customType": "HttpRequestBody", "schema": [ { "name": "deviceId", "kind": "optional", "type": "string", "description": "A persistent device identifier accepted in place of a monetateId (e.g., iOS identifierForVendor).", "example": "" }, { "name": "customerId", "kind": "optional", "type": "string", "description": "An identifer specific to a customer, regardless of the device they are on.", "example": "" }, { "name": "events", "kind": "required", "type": "array", "description": "An array of events to process.", "modelRef": "#/definitions/Event", "customType": "Event[]", "schema": [ { "name": "eventType", "kind": "required", "type": "string", "description": "A value that identifies the type of event.", "example": "" } ] }, { "name": "monetateId", "kind": "optional", "type": "string", "description": "A persistent device identifier accepted in place of deviceId. This identifier is generated by Monetate in response to a request containing neither deviceId nor monetateId, or generated and stored in the mt.v cookie on a domain using a Monetate JavaScript integration.", "example": "" }, { "name": "preview", "kind": "optional", "type": "string", "description": "A token to access actions for a specific variant of an experience, even if the experience is not actively running. The token is generated by clicking the PREVIEW button on the Experience Editor page in Monetate's UI, which will redirect to the client site, appending the token to the URL as ?preview=token, for use in the request.", "example": "" }, { "name": "channel", "kind": "optional", "type": "string", "description": "A string that identifies the account, domain, and instance associated with the request.", "example": "" }, { "name": "sdkVersion", "kind": "optional", "type": "string", "description": "A string that identifies the Monetate SDK used to generate the request.", "example": "" } ], "modelRef": "#/definitions/HttpRequestBody", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [] }, "responses": [ { "statusCode": "200", "description": "The request was succesful and the payload will include valid actions.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\n \"meta\": {\n \"code\": 200,\n \"errors\": [],\n \"warnings\": [],\n \"monetateId\": \"monetate id\"\n },\n \"data\": {\n \"responses\": [\n {\n \"requestId\": \"12345\",\n \"actions\": [\n {\n \"actionType\": \"Action\"\n }\n ]\n }\n ]\n }\n}\n", "description": "The request was succesful and the payload will include valid actions.", "customType": "HttpResponseBody", "schema": [ { "name": "data", "kind": "required", "type": "object", "description": "The data portion of the response.", "example": "{\n \"responses\": [\n {\n \"requestId\": \"12345\",\n \"actions\": [\n {\n \"actionType\": \"Action\"\n }\n ]\n }\n ]\n}\n", "modelRef": "#/definitions/ResponseData", "customType": "ResponseData", "schema": [ { "name": "responses", "kind": "optional", "type": "array", "description": "The array of all responses.", "modelRef": "#/definitions/Response", "customType": "Response[]", "schema": [ { "name": "requestId", "kind": "required", "type": "string", "description": "The request identifier tying the response back to an event.", "example": "" }, { "name": "actions", "kind": "required", "type": "array", "description": "The array of actions.", "modelRef": "#/definitions/Action", "customType": "Action[]", "schema": [ { "name": "actionType", "kind": "required", "type": "string", "description": "The value that identifies the type of action.", "example": "" }, { "name": "impressionId", "kind": "optional", "type": "string", "description": "A token to be used for recording managed impressions.", "example": "" }, { "name": "impressionReporting", "kind": "optional", "type": "array", "description": "This array identifies the experience and variant associated with the action. It's included for each action if the \"includeReporting\" option is set to true on the DecisionRequest event.", "modelRef": "#/definitions/ImpressionReporting", "customType": "ImpressionReporting[]", "schema": [ { "name": "experience_id", "kind": "required", "type": "integer", "description": "The unique identifier for the experience associated with the action.", "example": 0 }, { "name": "experience_label", "kind": "required", "type": "string", "description": "A static reporting label, set at experience activation, based on experience name.", "example": "" }, { "name": "experience_name", "kind": "required", "type": "string", "description": "The title of the experience associated with the action.", "example": "" }, { "name": "variant_label", "kind": "required", "type": "string", "description": "The name of the variant associated with the action.", "example": "" }, { "name": "is_control", "kind": "required", "type": "boolean", "description": "Whether the user was assigned to a control group for this action.", "example": "" }, { "name": "control_allocation", "kind": "required", "type": "", "description": "A value from 0.0 to 1.0 representing the percentage of traffic allocated to the control group.", "example": "" }, { "name": "experience_type", "kind": "required", "type": "string", "description": "The type of experience (e.g., \"100% Experience\" or \"Majority Fit\").", "example": "" }, { "name": "has_targets", "kind": "required", "type": "boolean", "description": "Indicates whether there are any WHO targets associated with the experience.", "example": "" }, { "name": "tags", "kind": "required", "type": "array", "description": "An array containing the tag names associated to the experience.", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ] } ] } ] }, { "name": "meta", "kind": "optional", "type": "object", "description": "The metadata portion of the response.", "example": "{\n \"code\": 200,\n \"errors\": [],\n \"warnings\": [],\n \"monetateId\": \"monetate id\"\n}\n", "modelRef": "#/definitions/Meta", "customType": "Meta", "schema": [ { "name": "code", "kind": "optional", "type": "integer", "description": "The HTTP status code associated with the response.", "example": 0 }, { "name": "errors", "kind": "optional", "type": "array", "description": "An array of objects describing any errors that occurred.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "monetateId", "kind": "optional", "type": "string", "description": "A unique device identifer generated by Monetate when neither deviceId nor monetateId are supplied in request, for persisting to device and sending in future requests. Any events received in request are associated with this monetateId.", "example": "" }, { "name": "warnings", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" } ] } ], "modelRef": "#/definitions/HttpResponseBody", "isExpanded": true } ] }, { "statusCode": "400", "description": "Invalid request.\nThe request was either malformated (did not follow this specification), or the data sent was invalid.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\n \"meta\": {\n \"code\": 200,\n \"errors\": [],\n \"warnings\": [],\n \"monetateId\": \"monetate id\"\n },\n \"data\": {\n \"responses\": [\n {\n \"requestId\": \"12345\",\n \"actions\": [\n {\n \"actionType\": \"Action\"\n }\n ]\n }\n ]\n }\n}\n", "description": "Invalid request.\nThe request was either malformated (did not follow this specification), or the data sent was invalid.", "customType": "HttpResponseBody", "schema": [ { "name": "data", "kind": "required", "type": "object", "description": "The data portion of the response.", "example": "{\n \"responses\": [\n {\n \"requestId\": \"12345\",\n \"actions\": [\n {\n \"actionType\": \"Action\"\n }\n ]\n }\n ]\n}\n", "modelRef": "#/definitions/ResponseData", "customType": "ResponseData", "schema": [ { "name": "responses", "kind": "optional", "type": "array", "description": "The array of all responses.", "modelRef": "#/definitions/Response", "customType": "Response[]", "schema": [ { "name": "requestId", "kind": "required", "type": "string", "description": "The request identifier tying the response back to an event.", "example": "" }, { "name": "actions", "kind": "required", "type": "array", "description": "The array of actions.", "modelRef": "#/definitions/Action", "customType": "Action[]", "schema": [ { "name": "actionType", "kind": "required", "type": "string", "description": "The value that identifies the type of action.", "example": "" }, { "name": "impressionId", "kind": "optional", "type": "string", "description": "A token to be used for recording managed impressions.", "example": "" }, { "name": "impressionReporting", "kind": "optional", "type": "array", "description": "This array identifies the experience and variant associated with the action. It's included for each action if the \"includeReporting\" option is set to true on the DecisionRequest event.", "modelRef": "#/definitions/ImpressionReporting", "customType": "ImpressionReporting[]", "schema": [ { "name": "experience_id", "kind": "required", "type": "integer", "description": "The unique identifier for the experience associated with the action.", "example": 0 }, { "name": "experience_label", "kind": "required", "type": "string", "description": "A static reporting label, set at experience activation, based on experience name.", "example": "" }, { "name": "experience_name", "kind": "required", "type": "string", "description": "The title of the experience associated with the action.", "example": "" }, { "name": "variant_label", "kind": "required", "type": "string", "description": "The name of the variant associated with the action.", "example": "" }, { "name": "is_control", "kind": "required", "type": "boolean", "description": "Whether the user was assigned to a control group for this action.", "example": "" }, { "name": "control_allocation", "kind": "required", "type": "", "description": "A value from 0.0 to 1.0 representing the percentage of traffic allocated to the control group.", "example": "" }, { "name": "experience_type", "kind": "required", "type": "string", "description": "The type of experience (e.g., \"100% Experience\" or \"Majority Fit\").", "example": "" }, { "name": "has_targets", "kind": "required", "type": "boolean", "description": "Indicates whether there are any WHO targets associated with the experience.", "example": "" }, { "name": "tags", "kind": "required", "type": "array", "description": "An array containing the tag names associated to the experience.", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ] } ] } ] } ] }, { "name": "meta", "kind": "optional", "type": "object", "description": "The metadata portion of the response.", "example": "{\n \"code\": 200,\n \"errors\": [],\n \"warnings\": [],\n \"monetateId\": \"monetate id\"\n}\n", "modelRef": "#/definitions/Meta", "customType": "Meta", "schema": [ { "name": "code", "kind": "optional", "type": "integer", "description": "The HTTP status code associated with the response.", "example": 0 }, { "name": "errors", "kind": "optional", "type": "array", "description": "An array of objects describing any errors that occurred.", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "monetateId", "kind": "optional", "type": "string", "description": "A unique device identifer generated by Monetate when neither deviceId nor monetateId are supplied in request, for persisting to device and sending in future requests. Any events received in request are associated with this monetateId.", "example": "" }, { "name": "warnings", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" } ] } ], "modelRef": "#/definitions/HttpResponseBody", "isExpanded": true } ] } ], "examples": { "languages": [ { "id": "Axs9hnautHT3vu2dc4mO5", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://engine.monetate.net/api/engine/v1/decide/{retailerShortname} \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"events\": [\n {\n \"eventType\": \"\"\n }\n ]\n }'" }, { "id": "6uaRdh7F_2vvVxs2qT4XH", "language": "php", "label": "PHP", "code": " 'https://engine.monetate.net/api/engine/v1/decide/{retailerShortname}',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_ENCODING => '',\n CURLOPT_MAXREDIRS => 10,\n CURLOPT_TIMEOUT => 0,\n CURLOPT_FOLLOWLOCATION => true,\n CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_POSTFIELDS =>'{\n \"events\": [\n {\n \"eventType\": \"\"\n }\n ]\n}',\n CURLOPT_HTTPHEADER => array(\n 'accept: application/json',\n 'content-type: application/json'\n ),\n));\n\n$response = curl_exec($curl);\n\ncurl_close($curl);\necho $response;\n" }, { "id": "04HaHja4Un7mAxbrK0K8E", "language": "javascript", "label": "JavaScript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"events\": [\n {\n \"eventType\": \"\"\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://engine.monetate.net/api/engine/v1/decide/{retailerShortname}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "O15HHQBA3WDO0cf9D83P9", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://engine.monetate.net/api/engine/v1/decide/{retailerShortname}\"\n\npayload = json.dumps({\n \"events\": [\n {\n \"eventType\": \"\"\n }\n ]\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" }, { "id": "KRdDUbblgd0dZH49ueMkd", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://engine.monetate.net/api/engine/v1/decide/{retailerShortname}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"events\": [\n {\n \"eventType\": \"\"\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" } ], "selectedLanguageId": "Axs9hnautHT3vu2dc4mO5" }, "results": { "languages": [ { "id": "I2OK2-lPcwBc3CzoeBcd6", "language": "200", "code": "// The request was succesful and the payload will include valid actions.\n{\n \"data\": {\n \"responses\": [\n {\n \"requestId\": \"\",\n \"actions\": [\n {\n \"actionType\": \"\",\n \"impressionId\": \"\",\n \"impressionReporting\": [\n {\n \"experience_id\": 0,\n \"experience_label\": \"\",\n \"experience_name\": \"\",\n \"variant_label\": \"\",\n \"is_control\": false,\n \"control_allocation\": \"\",\n \"experience_type\": \"\",\n \"has_targets\": false,\n \"tags\": [\n \"\"\n ]\n }\n ]\n }\n ]\n }\n ]\n },\n \"meta\": {\n \"code\": 0,\n \"errors\": [\n {}\n ],\n \"monetateId\": \"\",\n \"warnings\": [\n {}\n ]\n }\n}" }, { "id": "pcx54UJbMh1GRCTTyea-r", "language": "400", "code": "// Invalid request.\nThe request was either malformated (did not follow this specification), or the data sent was invalid.\n{\n \"data\": {\n \"responses\": [\n {\n \"requestId\": \"\",\n \"actions\": [\n {\n \"actionType\": \"\",\n \"impressionId\": \"\",\n \"impressionReporting\": [\n {\n \"experience_id\": 0,\n \"experience_label\": \"\",\n \"experience_name\": \"\",\n \"variant_label\": \"\",\n \"is_control\": false,\n \"control_allocation\": \"\",\n \"experience_type\": \"\",\n \"has_targets\": false,\n \"tags\": [\n \"\"\n ]\n }\n ]\n }\n ]\n }\n ]\n },\n \"meta\": {\n \"code\": 0,\n \"errors\": [\n {}\n ],\n \"monetateId\": \"\",\n \"warnings\": [\n {}\n ]\n }\n}" } ], "selectedLanguageId": "I2OK2-lPcwBc3CzoeBcd6" } }, "children": [ { "text": "" } ] }