Monetate Schema API

openapi: 3.2.0
info:
  title: Monetate Data Schema API
  description: The Monetate Data API allows you to create and send data across any channel in real time. This data is leveraged by Monetate's real-time decisioning engine to deliver 1:1 experiences across any channel.
  version: v1
servers:
- url: https://api.monetate.net/api/data/v1/{retailerShortname}/production
security:
- Token Authentication: []
tags:
- name: Schema
  description: Schema related endpoints.
paths:
  /schema/:
    get:
      tags:
      - Schema
      summary: Get Active Schema
      description: Returns a list of active Schema used by Monetate for experience decisioning.
      parameters:
      - name: row_count
        in: query
        description: Adds a field called `row_count` which is an Integer that is the number of available rows for targeting (there may be an hour delay between uploading data and this value updating)
        schema:
          type: boolean
      - name: latest_upload
        in: query
        description: "Adds a field called `last_file_upload` with the format:\n```\n\"last_file_upload\": {\n    \"status\": \"COMPLETE\",\n    \"upload_time\": \"2016-03-24T10:56:52.000000Z\",\n    \"import_start_time\": \"2017-04-04T18:05:34.000000Z\",\n    \"import_end_time\": \"2017-04-04T18:05:35.000000Z\",\n    \"validation_error\": \"\"\n}\n```"
        schema:
          type: boolean
      - name: usable_in_accounts
        in: query
        description: "Adds a field called `usable_in_accounts` which is an object describing the accounts where the dataset can be used for targeting.\n```\n\"usable_in_accounts\": [\n  {\n      \"name\": \"a-b6206def\",\n      \"instance\": \"p\",\n      \"domain\": \"fifthlevelfashion.com\"\n  },\n  {\n      \"name\": \"a-b6206def\",\n      \"instance\": \"p\",\n      \"domain\": \"fifthlevelfashion.us\"\n  }\n]\n```"
        schema:
          type: boolean
      responses:
        '200':
          description: A list of Schema definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaListResponse'
        '401':
          description: "Unauthorized. \n\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."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: 'Forbidden.


            The request included a token that has been revoked. Please contact your account administrator to generate a new token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: 'Unknown error.


            Please try again or contact your account manager for more information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
    post:
      tags:
      - Schema
      summary: Create a New Schema
      description: "To send data to Monetate, you must first create a new Schema.\n\n### Schema types\n\nThe API currently accepts the following types of data:\n\n* **Event**: Any data that contains a timestamp for the purposes of understanding when the specific events or interactions occurred in a time series.\n    * **type**: `event`\n    * **Required fields**: `identifier`, `event_time`\n* **Entity**: Any non-time series data\n    * **type**: `attribute`\n    * **Required fields**: `identifier`\n* **Product**: Product catalog data\n    * **type**: `product`\n\n### Fields\n\nA Schema consists of a set of fields defining its structure. You can include up to 40 fields in each Schema.\n\n#### Field Data Types\n\nThe API supports the following field data types:\n\n* `STRING`: Non-empty text without leading or trailing whitespace.\n* `MULTI_STRING`: Comma-separated string. As `STRING`, but allows multiple values separated by commas. See [Product Catalog Specification: Comma Escaping](https://docs.monetate.com/docs/product-catalog-specification#comma-escaping) regarding the necessary escaping rules.\n* `NUMBER`: An integer or decimal number.\n* `DATETIME`: A timestamp conforming to the ISO-8601 standard.\n* `BOOLEAN`: A true or false value.\n\n#### Field Attributes\n\nThe API allows attributes to be set on certain fields:\n\n* `data_type`: String attribute. The type of data allowed in this field (see 'Field Data Types').\n* `required`: Boolean attribute. Defaults to false. Allows certain attributes to be 'required' when submitting records.\n* `identifier`: Boolean attribute. Field used to identify a customer. Exactly one field may be the identifier.\n* `unique_key`: 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.\n* `event_time`: Boolean attribute. For events, the time that the event occurred.\n\nOnly identifier and unique key are considered 'required' fields when specified. All other fields are optional and are marked as null if absent."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schema'
        required: false
      responses:
        '201':
          description: Schema created. Content is the definition of the created Schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResponse'
            meta:
              example:
                code: 201
            data:
              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
        '400':
          description: "Validation error. \n\nOne or more values being sent was not in the correct format, or a required value was missing."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: "Unauthorized. \n\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."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: 'Forbidden.


            The request included a token that has been revoked. Please contact your account administrator to generate a new token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: 'Unknown error.


            Please try again or contact your account manager for more information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      x-codegen-request-body-name: schema
  /schema/{schema-name}/:
    get:
      tags:
      - Schema
      summary: Get Schema Details
      description: Returns a list of all data types and schemas.
      parameters:
      - name: schema-name
        in: path
        description: The name of the Schema.
        required: true
        schema:
          type: string
      - name: row_count
        in: query
        description: Adds a field called `row_count` which is an Integer that is the number of available rows for targeting (there may be an hour delay between uploading data and this value updating)
        schema:
          type: boolean
      - name: latest_upload
        in: query
        description: "Adds a field called `last_file_upload` with the format:\n```\n\"last_file_upload\": {\n    \"status\": \"COMPLETE\",\n    \"upload_time\": \"2016-03-24T10:56:52.000000Z\",\n    \"import_start_time\": \"2017-04-04T18:05:34.000000Z\",\n    \"import_end_time\": \"2017-04-04T18:05:35.000000Z\",\n    \"validation_error\": \"\"\n}\n```"
        schema:
          type: boolean
      responses:
        '200':
          description: A single Schema definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaResponse'
        '401':
          description: "Unauthorized. \n\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."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: 'Forbidden.


            The request included a token that has been revoked. Please contact your account administrator to generate a new token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: 'Not found.


            The resource you are trying to fetch does not exist, or has been deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: 'Unknown error.


            Please try again or contact your account manager for more information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
    patch:
      tags:
      - Schema
      summary: Update an Existing Schema
      description: 'Update an existing schema by either adding new columns or updating the Identifier Name.


        The request differs based on whether adding new columns or updating Identifier Name

        Must only supply either fields or named_identifier (but not both) in the params body.

        Response will return either fields or named_identifier, depending on which was supplied.'
      parameters:
      - name: schema-name
        in: path
        description: The name of the Schema.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaPatch'
        required: false
      responses:
        '200':
          description: Schema patched. Content is the definition of the modified Schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaPatchResponse'
            meta:
              example:
                code: 200
            data:
              example:
                fields:
                  existing_field:
                    data_type: STRING
                    unique_key: true
                  new_field:
                    data_type: STRING
                named_identifier: valid_named_identifier
        '400':
          description: "Validation error. \n\nOne or more values being sent was not in the correct format, or a required value was missing."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: "Unauthorized. \n\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."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: 'Forbidden.


            The request included a token that has been revoked. Please contact your account administrator to generate a new token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: 'Unknown error.


            Please try again or contact your account manager for more information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      x-codegen-request-body-name: fields
  /schematype/:
    get:
      tags:
      - Schema
      summary: List Schema Types
      description: Gets a list of the available Schema types and their specifications.
      responses:
        '200':
          description: A list of Schema Types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaTypeListResponse'
        '401':
          description: "Unauthorized. \n\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."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: 'Forbidden.


            The request included a token that has been revoked. Please contact your account administrator to generate a new token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: 'Not found.


            The resource you are trying to fetch does not exist, or has been deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: 'Unknown error.


            Please try again or contact your account manager for more information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
  /schematype/{schema-type}/:
    get:
      tags:
      - Schema
      summary: Get Schema Type Details
      description: Gets details for a Schema Type and its specification.
      parameters:
      - name: schema-type
        in: path
        description: Name of the schema type.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A Schema Type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaTypeResponse'
        '401':
          description: "Unauthorized. \n\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."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: 'Forbidden.


            The request included a token that has been revoked. Please contact your account administrator to generate a new token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: 'Not found.


            The resource you are trying to fetch does not exist, or has been deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: 'Unknown error.


            Please try again or contact your account manager for more information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
components:
  schemas:
    SchemaPatch:
      required:
      - fields
      type: object
      properties:
        fields:
          minProperties: 1
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Field'
          description: The fields that define the structure of this Schema.
      description: '

        Within a Schema, fields must have unique names.


        Columns passed in the fields property are added to the schema.'
      example:
        name: catalog
        type: event
        fields:
          new_field:
            data_type: STRING
    ResponseMeta:
      required:
      - code
      type: object
      properties:
        code:
          type: integer
          description: The http response code for this response.
          example: 200
        warnings:
          type: array
          description: A list of warnings associated with this response.
          example: []
          items:
            type: object
            additionalProperties: true
        errors:
          type: array
          description: A list of errors associated with this response.
          example: []
          items:
            type: object
            additionalProperties: true
    Field:
      required:
      - data_type
      type: object
      properties:
        data_type:
          type: string
          description: 'The data type for this field.


            Monetate supports five data types: STRING, MULTI_STRING, NUMBER, DATETIME, and BOOLEAN.'
          enum:
          - STRING
          - MULTI_STRING
          - BOOLEAN
          - DATETIME
          - NUMBER
          - GOOGLE_PRODUCT_CATEGORY
        identifier:
          type: boolean
          description: 'Indicates that this field can be linked to a Person ID for testing and targeting.


            The name of this schema.


            Schema names must begin with a letter and contain only letters, numbers, hyphens, and the underscore character.


            `data_type` must be a STRING.


            There must be exactly one Field designated as an identifier in your schema.'
        unique_key:
          type: boolean
          description: 'Indicates that this field is a unique key.


            `data_type` must be a STRING.


            Optionally, one field may be designated as a unique key in your schema.'
        event_time:
          type: boolean
          description: 'Indicates that this field represents the event time, the time which the event occurred.


            Must be data_type DATETIME.


            For schema''s with type==event, there must be exactly 1 field marked as the event time.'
      description: Representation of the properties of a Field within a Schema. Only appears within a Schema object's `fields` property.
    SchemaListResponse:
      required:
      - data
      - meta
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMetaPagination'
        data:
          type: array
          description: Data payload of this response.
          items:
            $ref: '#/components/schemas/Schema'
    Response:
      required:
      - data
      - meta
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          $ref: '#/components/schemas/ResponseAnyData'
    SchemaType:
      required:
      - fields
      - name
      type: object
      properties:
        name:
          maxLength: 64
          pattern: ^[A-Za-z][A-Za-z0-9_]*$
          type: string
          description: The name of the Schema Type.
        fields:
          minProperties: 0
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Field'
          description: The fields part of the Schema Type specification.
      description: Representation of the type of Schema that can be created.
      example:
        name: product
        fields:
          id:
            data_type: STRING
            identifier: true
            unique_key: true
            event_time: false
            required: true
          title:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: true
          description:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: true
          link:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: true
          image_link:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: true
          additional_image_link:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          mobile_link:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          availability:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          availability_date:
            data_type: DATETIME
            identifier: false
            unique_key: false
            event_time: false
            required: false
          expiration_date:
            data_type: DATETIME
            identifier: false
            unique_key: false
            event_time: false
            required: false
          price:
            data_type: NUMBER
            identifier: false
            unique_key: false
            event_time: false
            required: true
          sale_price:
            data_type: NUMBER
            identifier: false
            unique_key: false
            event_time: false
            required: false
          sale_price_effective_date_begin:
            data_type: DATETIME
            identifier: false
            unique_key: false
            event_time: false
            required: false
          sale_price_effective_date_end:
            data_type: DATETIME
            identifier: false
            unique_key: false
            event_time: false
            required: false
          loyalty_points:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          product_type:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: true
          brand:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          mpn:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          condition:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          adult:
            data_type: BOOLEAN
            identifier: false
            unique_key: false
            event_time: false
            required: false
          multipack:
            data_type: NUMBER
            identifier: false
            unique_key: false
            event_time: false
            required: false
          is_bundle:
            data_type: BOOLEAN
            identifier: false
            unique_key: false
            event_time: false
            required: false
          energy_efficiency_class:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          age_group:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          color:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          gender:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          material:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          pattern:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          quantity:
            data_type: NUMBER
            identifier: false
            unique_key: false
            event_time: false
            required: false
          size:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          size_type:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          item_group_id:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          promotion_id:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          shipping:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          shipping_label:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          shipping_weight:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          shipping_length:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          shipping_height:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          shipping_width:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
          tax:
            data_type: STRING
            identifier: false
            unique_key: false
            event_time: false
            required: false
    SchemaResponse:
      required:
      - data
      - meta
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          $ref: '#/components/schemas/Schema'
    SchemaTypeResponse:
      required:
      - data
      - meta
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          $ref: '#/components/schemas/SchemaType'
    ResponsePagination:
      type: object
      properties:
        count:
          type: integer
          description: The number of items returned in this response.
          example: 1
        next:
          type: string
          description: A URL to the next group of items, if any.
        previous:
          type: string
          description: A URL to the previous group of items, if any.
    Schema:
      required:
      - fields
      - name
      type: object
      properties:
        name:
          maxLength: 64
          pattern: ^[A-Za-z][A-Za-z0-9_]*$
          type: string
          description: 'The name of the Schema.


            Schema names must begin with a letter and contain only letters, numbers, hyphens, and the underscore character.


            Maximum length of 64 characters.'
        type:
          type: string
          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
        fields:
          minProperties: 1
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Field'
          description: The fields that define the structure of this Schema.
        created_date:
          type: string
          description: The time the schema was created.
          format: date-time
          readOnly: true
        id:
          type: integer
          description: Monetate internal identifier for this schema.
          readOnly: true
        named_identifier:
          type: string
          description: '

            Identifier Name to associate with the schema.


            Identifier Name must be set for the schema to be used.'
      description: 'Representation of a Schema object.  A schema must have a name, and at least one field.


        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.


        Within a Schema, fields must have unique names.


        Exactly one field must be designated as the `identifier`.  This field will be used to link to a Person ID for testing and targeting.


        Optionally, one field may be designated as a `unique_key`.  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.'
      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
    ResponseAnyData:
      type: object
      additionalProperties: true
    SchemaTypeListResponse:
      required:
      - data
      - meta
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMetaPagination'
        data:
          type: array
          description: Data payload of this response.
          items:
            $ref: '#/components/schemas/SchemaType'
    SchemaPatchResponse:
      required:
      - data
      - meta
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          $ref: '#/components/schemas/SchemaPatch'
    ResponseMetaPagination:
      allOf:
      - $ref: '#/components/schemas/ResponseMeta'
      - $ref: '#/components/schemas/ResponsePagination'
  securitySchemes:
    Token_Authentication:
      type: apiKey
      description: The Monetate Data API uses Token Authentication, so requests to the Data API must include a valid, active authentication token. Include an `Authorization` header with the value `Token [token_string]` with every request. See [Auth API](https://developer.monetate.com/auth-api) for information on obtaining the *token_string*.
      name: Authorization
      in: header
x-original-swagger-version: '2.0'