Update a Customer Attributes Dataset via the Data API

This content is only for clients with the one-click DATASETS option in the top navigation bar. If you click DATASETS and see Product Data and Customer Data listed as menu options, then this content doesn't apply to your account. Instead, see the alternate version of this documentation.

You have three options to deliver customer data files to the Monetate platform:

  • API: Automatically pass data to Monetate in real time with the Monetate Data API
  • SFTP: Automatically deliver full or partial updates to datasets via an SFTP connection
  • Data file uploads: Upload full or partial files using a drag-and-drop option or inputting an Amazon S3 pre-signed URL within a wizard in the platform

Monetate's APIs empower you to send it data in real time. A RESTful API programmatically transfers information over the Web through a predefined schema. Monetate created many different endpoints with specific requirements that perform various actions or return various data.

The Monetate Data API allows you to create and send data to the platform that it can leverage to deliver individual decisions and recommendations across channels. As APIs become the driving force behind continuous and automated data exchange, you can securely connect your applications to Monetate.

Monetate currently accepts data that contains a timestamp for the purposes of understanding when specific events or interactions occurred in a time series and non-time series data. These are commonly referred to as entities or attributes. Before sending data to Monetate, you must fulfill a few prerequisites.

Creating API Users and Public Keys

API keys allow you to generate authentication credentials that are separate from your username and password for the platform. To successfully set up an integration between your Monetate account and your applications, you must generate unique API users and create public keys for those users that you can revoke at any time.

To ensure secure communication, the platform uses public-private key pairs. Public keys are made available to everyone, including Monetate, but private keys remain confidential to their respective owners (just you). Whatever is encrypted with a public key may only be decrypted via the corresponding private key and vice versa.

For more information about configuring API users and public keys, refer to Manage API Keys.

Establishing Authentication

Logging in with a username and password is one example of authentication. When you authenticate with a server, you prove your identity to the server by telling it information that only you know. Once the server knows who you are, it can trust you and disclose the private data in your account.

Monetate's authentication model allows your applications to authenticate directly to it using a JSON Web token (JWT) signed with your private key. The Auth API allows your application to request these access tokens.

After you create your public-private key pair and submit your public key, use your private key to sign your API request, and then your public key will be used to verify it to receive your token.

For help constructing your JWT assertion, refer to the API documentation that is specific to your account. Find it by first selecting API Documentation from the settings cog within the platform, and then clicking the API Information option under the Monetate Auth API heading in the left-hand navigation.

Callout of the Monetate Auth API information found in the API Documentation in the Monetate platform

Multiple access tokens can be live at any given time, and the expiration for each token is independent of the expiration of any other access tokens.

Configuring Schema, Identifiers, and Identifier Names

A schema is the organization or structure of the data in a dataset. You must establish the schema for a dataset before sending data to Monetate. Follow the steps in Upload a Customer Attributes Dataset to create a schema using the wizard within the platform.

Creating a Customer Attributes dataset schema via the API is not recommended at this time. You can, however, add attributes to an existing dataset schema through the Data API.

During the process of creating a schema, you can select or create an Identifier Name for the dataset that you can use to connect it to one or more ID Collectors. You can also add the Identifier Name afterwards.

You cannot use a dataset until you set an Identifier Name for it.

Identifier Names and their associations with ID Collectors allow you to leverage cross-device identification of your site visitors.

Posting Data

Once you create a schema, you can update or create a new data record within that schema with the Data API to immediately react to customer behavior for the purpose of optimization.

Detailed information about endpoints and request syntax is accessible in the API documentation that is specific to your account. Find it by first selecting API Documentation from the settings cog within the platform, and then clicking the API Information option under the Monetate Data API heading in the left-hand navigation.

Monetate Data API information found in the API Documentation in the Monetate platform

The Data API section is dynamically generated based on your schema. Therefore, you must first create a schema for the Monetate Data API section to appear in the API documentation accessible via the settings cog.

Validating Data API Records

To verify that dataset records have been updated successfully, you can use a Data API endpoint that supports requests for single records. You cannot use this endpoint to download bulk records or for automated testing, but you can use it to manually spot-check individual records within a dataset.

The endpoint format is as follows:

GET https://api.monetate.net/api/data/v1/{schema-name}/production/data/?id={record_id}

This GET endpoint is intended for you to manually validate individual records and is strictly rate-limited. A maximum of one request per second is supported.

Ensure you replace {schema-name} and {record_id} with the specific schema name and record ID that you want to check.