Create and manage data schemas and send customer, product and catalog data into Monetate in real time for use by the decision engine. Covers schema CRUD, schema types, upload history, row-level data POST/GET and default product-catalog assignment (single and bulk), plus customer data-privacy operations.
openapi: 3.0.1
info:
title: Monetate Data 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.
- name: Upload
description: File upload related endpoints.
- name: Data
description: Data related endpoints.
- name: Product Catalog
description: Product Catalog related endpoints.
- name: Customer Data Privacy
description: Product Catalog 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:
```
"last_file_upload": {
"status": "COMPLETE",
"upload_time": "2016-03-24T10:56:52.000000Z",
"import_start_time": "2017-04-04T18:05:34.000000Z",
"import_end_time": "2017-04-04T18:05:35.000000Z",
"validation_error": ""
}
```
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.
```
"usable_in_accounts": [
{
"name": "a-b6206def",
"instance": "p",
"domain": "fifthlevelfashion.com"
},
{
"name": "a-b6206def",
"instance": "p",
"domain": "fifthlevelfashion.us"
}
]
```
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.
### Schema types
The API currently accepts the following types of data:
* **Event**: Any data that contains a timestamp for the purposes of understanding when the specific events or interactions occurred in a time series.
* **type**: `event`
* **Required fields**: `identifier`, `event_time`
* **Entity**: Any non-time series data
* **type**: `attribute`
* **Required fields**: `identifier`
* **Product**: Product catalog data
* **type**: `product`
### Fields
A Schema consists of a set of fields defining its structure. You can include up to 40 fields in each Schema.
#### Field Data Types
The API supports the following field data types:
* `STRING`: Non-empty text without leading or trailing whitespace.
* `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.
* `NUMBER`: An integer or decimal number.
* `DATETIME`: A timestamp conforming to the ISO-8601 standard.
* `BOOLEAN`: A true or false value.
#### Field Attributes
The API allows attributes to be set on certain fields:
* `data_type`: String attribute. The type of data allowed in this field (see 'Field Data Types').
* `required`: Boolean attribute. Defaults to false. Allows certain attributes to be 'required' when submitting records.
* `identifier`: Boolean attribute. Field used to identify a customer. Exactly one field may be the identifier.
* `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.
* `event_time`: Boolean attribute. For events, the time that the event occurred.
Only 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:
```
"last_file_upload": {
"status": "COMPLETE",
"upload_time": "2016-03-24T10:56:52.000000Z",
"import_start_time": "2017-04-04T18:05:34.000000Z",
"import_end_time": "2017-04-04T18:05:35.000000Z",
"validation_error": ""
}
```
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'
/upload/{schema-name}/:
get:
tags:
- Upload
summary: Get Upload History
description: |-
Returns the most recent uploads for the Schema provided. Can be used for upload history or the view the status of a currently processed upload.
Uploads will appear once file is completely upload to Monetate. SFTP uploads appear when they are scanned and disappear from the SFTP drop location.
Uploads are sorted by upload_time in descending order, so the most recent upload will always be first in the list.
parameters:
- name: schema-name
in: path
description: The name of the Schema.
required: true
schema:
type: string
responses:
"200":
description: A list of file uploads.
content:
application/json:
schema:
$ref: '#/components/schemas/FileUploadListResponse'
"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'
/data/example_schema/:
get:
tags:
- Data
summary: 'Get Data for example_schema '
description: "Get an existing data record within the schema `example_schema`.\n\
\nAllows querying of an existing record. The record ID must be passed as\
\ a query parameter, \ne.g. `?id=ABC12345`. GET requests are intended solely\
\ for manual spot-checking of data \nand must not be used in any automated\
\ queries, including test suites or health checks. \nAs such, they are strictly\
\ rate-limited. A maximum of 1 GET request per second is permitted."
responses:
"200":
description: The requested record was found in the schema.
content:
application/json:
schema:
$ref: '#/components/schemas/example_schemaDataResponse'
"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'
"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'
"429":
description: |-
Too many requests.
The user has sent too many requests in a given amount of time to a rate-limited endpoint.
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: data
post:
tags:
- Data
summary: 'Post Data for example_schema '
description: |-
Creates new data records within the schema `example_schema`.
If your request contains a unique key that matches a record already received by Monetate, the record is updated with the latest data.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/example_schemaDataRequest'
required: false
responses:
"201":
description: Data was posted for the schema and will be made available for
targetting.
content:
application/json:
schema:
$ref: '#/components/schemas/example_schemaDataResponse'
"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'
"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'
x-codegen-request-body-name: data
/defaultcatalog/:
get:
tags:
- Product Catalog
summary: List Account Defaults
description: List all account default catalogs for retailer
responses:
"200":
description: A list of default account catalogs
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultAccountCatalogListResponse'
"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'
post:
tags:
- Product Catalog
summary: Set Account Default
description: Set a default catalog for an account
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultAccountCatalog'
required: false
responses:
"201":
description: The defaulted product catalog and account
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultAccountCatalogCreatedResponse'
meta:
example:
code: 201
data:
example:
account: "123"
schema: "456"
"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'
x-codegen-request-body-name: defaultaccountcatalog
/bulk-defaultcatalog/:
post:
tags:
- Product Catalog
summary: Bulk Set Account Defaults
description: Set default catalogs for accounts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultAccountCatalogBulk'
required: false
responses:
"201":
description: A list of the defaulted product catalogs and accounts
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultAccountCatalogBulkCreatedResponse'
"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'
x-codegen-request-body-name: defaultaccountcatalogbulk
components:
schemas:
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
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."
ResponseMetaPagination:
allOf:
- $ref: '#/components/schemas/ResponseMeta'
- $ref: '#/components/schemas/ResponsePagination'
ResponseAnyData:
type: object
additionalProperties: true
Response:
required:
- data
- meta
type: object
properties:
meta:
$ref: '#/components/schemas/ResponseMeta'
data:
$ref: '#/components/schemas/ResponseAnyData'
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:
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/monetate/refs/heads/main/openapi/monetate-data-api-openapi.yml