---
title: Create a New Schema
slug: data-api/create-a-new-schema
docTags: 
createdAt: 2026-05-15T19:39:37.743Z
---

{
  "id": "g7khKkJYFEKMOblTEYwMi",
  "type": "api-oas-v2",
  "data": {
    "method": "POST",
    "url": "https://api.monetate.net/api/data/v1/{retailerShortname}/production/schema/",
    "servers": [
      {
        "url": "https://api.monetate.net/api/data/v1/{retailerShortname}/production/schema/"
      }
    ],
    "name": "Create a New Schema",
    "description": "<p>To send data to Monetate, you must first create a new Schema.</p>\n<h3>Schema types</h3>\n<p>The API currently accepts the following types of data:</p>\n<ul>\n<li><strong>Event</strong>: Any data that contains a timestamp for the purposes of understanding when the specific events or interactions occurred in a time series.\n<ul>\n<li><strong>type</strong>: <code>event</code></li>\n<li><strong>Required fields</strong>: <code>identifier</code>, <code>event_time</code></li>\n</ul>\n</li>\n<li><strong>Entity</strong>: Any non-time series data\n<ul>\n<li><strong>type</strong>: <code>attribute</code></li>\n<li><strong>Required fields</strong>: <code>identifier</code></li>\n</ul>\n</li>\n<li><strong>Product</strong>: Product catalog data\n<ul>\n<li><strong>type</strong>: <code>product</code></li>\n</ul>\n</li>\n</ul>\n<h3>Fields</h3>\n<p>A Schema consists of a set of fields defining its structure. You can include up to 40 fields in each Schema.</p>\n<h4>Field Data Types</h4>\n<p>The API supports the following field data types:</p>\n<ul>\n<li><code>STRING</code>: Non-empty text without leading or trailing whitespace.</li>\n<li><code>MULTI_STRING</code>: Comma-separated string. As <code>STRING</code>, but allows multiple values separated by commas. See <a href=\"https://docs.monetate.com/docs/product-catalog-specification#comma-escaping\" target=\"_blank\">Product Catalog Specification: Comma Escaping</a> regarding the necessary escaping rules.</li>\n<li><code>NUMBER</code>: An integer or decimal number.</li>\n<li><code>DATETIME</code>: A timestamp conforming to the ISO-8601 standard.</li>\n<li><code>BOOLEAN</code>: A true or false value.</li>\n</ul>\n<h4>Field Attributes</h4>\n<p>The API allows attributes to be set on certain fields:</p>\n<ul>\n<li><code>data_type</code>: String attribute. The type of data allowed in this field (see 'Field Data Types').</li>\n<li><code>required</code>: Boolean attribute. Defaults to false. Allows certain attributes to be 'required' when submitting records.</li>\n<li><code>identifier</code>: Boolean attribute. Field used to identify a customer. Exactly one field may be the identifier.</li>\n<li><code>unique_key</code>: Boolean attribute. Unique identifier for the record which can be used to update the record in the future. Only one field may be the unique_key.</li>\n<li><code>event_time</code>: Boolean attribute. For events, the time that the event occurred.</li>\n</ul>\n<p>Only identifier and unique key are considered 'required' fields when specified. All other fields are optional and are marked as null if absent.</p>",
    "contentType": "application/json",
    "request": {
      "pathParameters": [],
      "headerParameters": [
        {
          "name": "accept",
          "type": "string",
          "kind": "optional",
          "description": "Generated from available response content types",
          "enum": [
            "application/json",
            "meta",
            "data"
          ],
          "default": "application/json"
        }
      ],
      "queryParameters": [],
      "bodyDataParameters": [
        {
          "kind": "optional",
          "name": "body",
          "type": "object",
          "example": "{\"name\":\"purchase_event\",\"named_identifier\":\"valid_named_identifier\",\"type\":\"event\",\"fields\":{\"purchase_id\":{\"data_type\":\"STRING\",\"unique_key\":true},\"customer_id\":{\"data_type\":\"STRING\",\"identifier\":true},\"purchase_time\":{\"data_type\":\"DATETIME\",\"event_time\":true},\"product_id\":{\"data_type\":\"STRING\"},\"product_category\":{\"data_type\":\"STRING\"},\"product_price\":{\"data_type\":\"NUMBER\"}}}",
          "description": "<p>Representation of a Schema object.  A schema must have a name, and at least one field.</p>\n<p>Schemata for your account must have unique names.  If you are trying to re-create a Schema that already exists, please delete the old one first.</p>\n<p>Within a Schema, fields must have unique names.</p>\n<p>Exactly one field must be designated as the <code>identifier</code>.  This field will be used to link to a Person ID for testing and targeting.</p>\n<p>Optionally, one field may be designated as a <code>unique_key</code>.  If a Schema defines a unique key, then only one record can exist in your data for a given value of the unique key.  Successive data updates with the same unique key value will replace earlier data updates.  If no unique key is defined, then all data updates will be considered new data and will never replace earlier data.</p>",
          "customType": "Schema",
          "schema": [
            {
              "name": "name",
              "kind": "required",
              "type": "string",
              "description": "<p>The name of the Schema.</p>\n<p>Schema names must begin with a letter and contain only letters, numbers, hyphens, and the underscore character.</p>\n<p>Maximum length of 64 characters.</p>",
              "maxLength": 64,
              "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
            },
            {
              "name": "type",
              "kind": "optional",
              "type": "string<agil_one | attribute | behavioral_trigger | custom_list | customer_data_privacy | email_metadata | event | inventory | product | product_recommendation | purchase>",
              "description": "The type of this schema.",
              "enum": [
                "agil_one",
                "attribute",
                "behavioral_trigger",
                "custom_list",
                "customer_data_privacy",
                "email_metadata",
                "event",
                "inventory",
                "product",
                "product_recommendation",
                "purchase"
              ]
            },
            {
              "name": "fields",
              "kind": "required",
              "type": "map",
              "description": "The fields that define the structure of this Schema.",
              "example": "",
              "customType": "map<string, Field>",
              "schema": []
            },
            {
              "name": "named_identifier",
              "kind": "optional",
              "type": "string",
              "description": "\nIdentifier Name to associate with the schema.\n\nIdentifier Name must be set for the schema to be used."
            }
          ],
          "modelRef": "#/components/schemas/Schema",
          "isExpanded": true
        }
      ],
      "formDataParameters": [],
      "oAuthParameters": [
        {
          "id": "Token Authentication",
          "name": "Authorization",
          "kind": "optional",
          "type": "apiKey",
          "description": "<p>The Monetate Data API uses Token Authentication, so requests to the Data API must include a valid, active authentication token. Include an <code>Authorization</code> header with the value <code>Token [token_string]</code> with every request. See <a href=\"https://developer.monetate.com/auth-api\" target=\"_blank\">Auth API</a> for information on obtaining the <em>token_string</em>.</p>",
          "in": "header"
        }
      ],
      "cookieParameters": []
    },
    "responses": [
      {
        "statusCode": "201",
        "description": "Schema created. Content is the definition of the created Schema.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "SchemaResponse",
            "schema": [
              {
                "name": "meta",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseMeta",
                "customType": "ResponseMeta",
                "schema": [
                  {
                    "name": "code",
                    "kind": "required",
                    "type": "integer",
                    "description": "The http response code for this response.",
                    "example": 200
                  },
                  {
                    "name": "warnings",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of warnings associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "errors",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of errors associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  }
                ]
              },
              {
                "name": "data",
                "kind": "required",
                "type": "object",
                "description": "<p>Representation of a Schema object.  A schema must have a name, and at least one field.</p>\n<p>Schemata for your account must have unique names.  If you are trying to re-create a Schema that already exists, please delete the old one first.</p>\n<p>Within a Schema, fields must have unique names.</p>\n<p>Exactly one field must be designated as the <code>identifier</code>.  This field will be used to link to a Person ID for testing and targeting.</p>\n<p>Optionally, one field may be designated as a <code>unique_key</code>.  If a Schema defines a unique key, then only one record can exist in your data for a given value of the unique key.  Successive data updates with the same unique key value will replace earlier data updates.  If no unique key is defined, then all data updates will be considered new data and will never replace earlier data.</p>",
                "example": "{\"name\":\"purchase_event\",\"named_identifier\":\"valid_named_identifier\",\"type\":\"event\",\"fields\":{\"purchase_id\":{\"data_type\":\"STRING\",\"unique_key\":true},\"customer_id\":{\"data_type\":\"STRING\",\"identifier\":true},\"purchase_time\":{\"data_type\":\"DATETIME\",\"event_time\":true},\"product_id\":{\"data_type\":\"STRING\"},\"product_category\":{\"data_type\":\"STRING\"},\"product_price\":{\"data_type\":\"NUMBER\"}}}",
                "modelRef": "#/components/schemas/Schema",
                "customType": "Schema",
                "schema": [
                  {
                    "name": "name",
                    "kind": "required",
                    "type": "string",
                    "description": "<p>The name of the Schema.</p>\n<p>Schema names must begin with a letter and contain only letters, numbers, hyphens, and the underscore character.</p>\n<p>Maximum length of 64 characters.</p>",
                    "maxLength": 64,
                    "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
                  },
                  {
                    "name": "type",
                    "kind": "optional",
                    "type": "string<agil_one | attribute | behavioral_trigger | custom_list | customer_data_privacy | email_metadata | event | inventory | product | product_recommendation | purchase>",
                    "description": "The type of this schema.",
                    "enum": [
                      "agil_one",
                      "attribute",
                      "behavioral_trigger",
                      "custom_list",
                      "customer_data_privacy",
                      "email_metadata",
                      "event",
                      "inventory",
                      "product",
                      "product_recommendation",
                      "purchase"
                    ]
                  },
                  {
                    "name": "fields",
                    "kind": "required",
                    "type": "map",
                    "description": "The fields that define the structure of this Schema.",
                    "example": "",
                    "customType": "map<string, Field>",
                    "schema": []
                  },
                  {
                    "name": "created_date",
                    "kind": "optional",
                    "type": "string<date-time>",
                    "readOnly": true,
                    "description": "The time the schema was created.",
                    "format": "date-time"
                  },
                  {
                    "name": "id",
                    "kind": "optional",
                    "type": "integer",
                    "readOnly": true,
                    "description": "Monetate internal identifier for this schema."
                  },
                  {
                    "name": "named_identifier",
                    "kind": "optional",
                    "type": "string",
                    "description": "\nIdentifier Name to associate with the schema.\n\nIdentifier Name must be set for the schema to be used."
                  }
                ]
              }
            ],
            "modelRef": "#/components/schemas/SchemaResponse",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "400",
        "description": "<p>Validation error.</p>\n<p>One or more values being sent was not in the correct format, or a required value was missing.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "Response",
            "schema": [
              {
                "name": "meta",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseMeta",
                "customType": "ResponseMeta",
                "schema": [
                  {
                    "name": "code",
                    "kind": "required",
                    "type": "integer",
                    "description": "The http response code for this response.",
                    "example": 200
                  },
                  {
                    "name": "warnings",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of warnings associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "errors",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of errors associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  }
                ]
              },
              {
                "name": "data",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseAnyData",
                "customType": "ResponseAnyData",
                "schema": []
              }
            ],
            "modelRef": "#/components/schemas/Response",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "401",
        "description": "<p>Unauthorized.</p>\n<p>The request did not include a token, or the token provided was invalid. Please ensure that your token is correct and that the Authorization header is properly formatted.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "Response",
            "schema": [
              {
                "name": "meta",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseMeta",
                "customType": "ResponseMeta",
                "schema": [
                  {
                    "name": "code",
                    "kind": "required",
                    "type": "integer",
                    "description": "The http response code for this response.",
                    "example": 200
                  },
                  {
                    "name": "warnings",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of warnings associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "errors",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of errors associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  }
                ]
              },
              {
                "name": "data",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseAnyData",
                "customType": "ResponseAnyData",
                "schema": []
              }
            ],
            "modelRef": "#/components/schemas/Response",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "403",
        "description": "Forbidden.\n\nThe request included a token that has been revoked. Please contact your account administrator to generate a new token.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "Response",
            "schema": [
              {
                "name": "meta",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseMeta",
                "customType": "ResponseMeta",
                "schema": [
                  {
                    "name": "code",
                    "kind": "required",
                    "type": "integer",
                    "description": "The http response code for this response.",
                    "example": 200
                  },
                  {
                    "name": "warnings",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of warnings associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "errors",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of errors associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  }
                ]
              },
              {
                "name": "data",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseAnyData",
                "customType": "ResponseAnyData",
                "schema": []
              }
            ],
            "modelRef": "#/components/schemas/Response",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "500",
        "description": "Unknown error.\n\nPlease try again or contact your account manager for more information.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "Response",
            "schema": [
              {
                "name": "meta",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseMeta",
                "customType": "ResponseMeta",
                "schema": [
                  {
                    "name": "code",
                    "kind": "required",
                    "type": "integer",
                    "description": "The http response code for this response.",
                    "example": 200
                  },
                  {
                    "name": "warnings",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of warnings associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "errors",
                    "kind": "optional",
                    "type": "array",
                    "description": "A list of errors associated with this response.",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  }
                ]
              },
              {
                "name": "data",
                "kind": "required",
                "type": "object",
                "description": "",
                "modelRef": "#/components/schemas/ResponseAnyData",
                "customType": "ResponseAnyData",
                "schema": []
              }
            ],
            "modelRef": "#/components/schemas/Response",
            "isExpanded": true
          }
        ]
      }
    ],
    "hasXCodeSamples": false,
    "examples": {
      "languages": [
        {
          "id": "O0a-PMs2N0LWyR6u9MdEi",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request POST \\\n     --url https://api.monetate.net/api/data/v1/{retailerShortname}/production/schema/ \\\n     --header 'accept: application/json' \\\n     --header 'content-type: application/json' \\\n     --data '{\n     \"name\": \"\",\n     \"fields\": \"\"\n     }'"
        },
        {
          "id": "Bh1T3EkApM5F5gQFS6y4d",
          "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   \"name\": \"\",\n   \"fields\": \"\"\n});\n\nvar requestOptions = {\n   method: 'POST',\n   headers: myHeaders,\n   body: raw,\n   redirect: 'follow'\n};\n\nfetch(\"https://api.monetate.net/api/data/v1/{retailerShortname}/production/schema/\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "njtmG8bboDIJQkK28KJmQ",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.monetate.net/api/data/v1/{retailerShortname}/production/schema/\")\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   \"name\": \"\",\n   \"fields\": \"\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
        },
        {
          "id": "dWe6uam8eHEIQ3G7pyFHi",
          "language": "python",
          "label": "Python",
          "code": "import requests\nimport json\n\nurl = \"https://api.monetate.net/api/data/v1/{retailerShortname}/production/schema/\"\n\npayload = json.dumps({\n   \"name\": \"\",\n   \"fields\": \"\"\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"
        }
      ],
      "selectedLanguageId": "O0a-PMs2N0LWyR6u9MdEi"
    },
    "results": {
      "languages": [
        {
          "id": "c4aTPiHmLMIYxWelKxgB1",
          "language": "201",
          "code": "// Schema created. Content is the definition of the created Schema.\n{\n  \"meta\": {\n    \"code\": 200,\n    \"warnings\": [\n      {}\n    ],\n    \"errors\": [\n      {}\n    ]\n  },\n  \"data\": {\n    \"name\": \"\",\n    \"type\": \"\",\n    \"fields\": \"\",\n    \"created_date\": \"\",\n    \"id\": 0,\n    \"named_identifier\": \"\"\n  }\n}"
        },
        {
          "id": "j1AAJMHyx-3eMafSixTKH",
          "language": "400",
          "code": "// Validation error.\nOne or more values being sent was not in the correct format, or a required value was missing.\n{\n  \"meta\": {\n    \"code\": 200,\n    \"warnings\": [\n      {}\n    ],\n    \"errors\": [\n      {}\n    ]\n  },\n  \"data\": {}\n}"
        },
        {
          "id": "OOzT5UBlRyTJrfxRToP3-",
          "language": "401",
          "code": "// Unauthorized.\nThe request did not include a token, or the token provided was invalid. Please ensure that your token is correct and that the Authorization header is properly formatted.\n{\n  \"meta\": {\n    \"code\": 200,\n    \"warnings\": [\n      {}\n    ],\n    \"errors\": [\n      {}\n    ]\n  },\n  \"data\": {}\n}"
        },
        {
          "id": "q4TRY2m8ccWreOA8VKSlU",
          "language": "403",
          "code": "// Forbidden.\n\nThe request included a token that has been revoked. Please contact your account administrator to generate a new token.\n{\n  \"meta\": {\n    \"code\": 200,\n    \"warnings\": [\n      {}\n    ],\n    \"errors\": [\n      {}\n    ]\n  },\n  \"data\": {}\n}"
        },
        {
          "id": "_pVp9zFqb3f-a9WuA__C0",
          "language": "500",
          "code": "// Unknown error.\n\nPlease try again or contact your account manager for more information.\n{\n  \"meta\": {\n    \"code\": 200,\n    \"warnings\": [\n      {}\n    ],\n    \"errors\": [\n      {}\n    ]\n  },\n  \"data\": {}\n}"
        }
      ],
      "selectedLanguageId": "c4aTPiHmLMIYxWelKxgB1"
    }
  },
  "children": [
    {
      "text": ""
    }
  ]
}