Event Types API

Manage mapping definitions with the API

This page explains how to use the Mappings API to create, read, update, and delete Stedi mapping definitions. You can also do these actions in the Mappings UI.

Before you begin, we recommend reviewing the Mapping Definition Overview.

Create a mapping definition

You create a mapping definition by POSTing to https://mappings.us.stedi.com/2021-06-01/mappings. At the very least, your mapping definition should have a name, mapping type, and a few mapping expressions.

POST https://mappings.us.stedi.com/2021-06-01/mappings HTTP/1.1
"Authorization: ${STEDI_API_KEY}"
Content-Type: application/json

{
  "name": "A minimal example",
  "type": "only_mapped_keys",
  "mapping": "{ \"total\": item.quantity * item.unit_price }"
}

The mapping expressions look like JSON, but they’re not. JSONata has all kinds of syntax that isn’t valid JSON. That’s why you need to provide the mapping expressions inside of a string.

Include a lookup table

You can add one or more lookup tables by providing the lookup_tables field. Every lookup table must have a name and a set of values.

POST https://mappings.us.stedi.com/2021-06-01/mappings HTTP/1.1 "Authorization: ${STEDI_API_KEY}" Content-Type: application/json

{
  "name": "A lookup table example",
  "type": "only_mapped_keys",
  "mapping": "{ \"country\": $lookupTable($tables.countries, \"german\", land).english }",
  "lookup_tables": [
    {
      "name": "countries",
      "values": [
        {
          "english": "United States",
          "spanish": "Estados Unidos",
          "german": "Vereinigte Staaten"
        },
        {
          "english": "Mexico",
          "spanish": "México",
          "german": "Mexiko"
        },
        {
          "english": "Germany",
          "spanish": "Alemania",
          "german": "Deutschland"
        }
      ]
    }
  ]
}

Response

The response contains a copy of the mapping definition you just created, plus a couple of extra fields.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "01AB3DEF4GHIJ5KL67MNOP8QR9",
  "name": "A minimal example",
  "type": "only_mapped_keys",
  "mapping": "{ \"total\": item.quantity * item.unit_price }"
  "created_at": "2022-01-01T20:22:01.01Z",
  "updated_at": "2022-01-01T20:22:01.01Z"
}

Retrieve a mapping definition

ou retrieve a mapping definition by GETting it from https://mappings.us.stedi.com/2021-06-01/mappings/mapping_id. The response is identical to the one you received when you created the mapping definition. In other words, it’s the mapping definition as you specified it, supplemented with the fields id, created_at, and updated_at.

Update a mapping definition

You update a mapping definition by PUTting a new version at https://mappings.us.stedi.com/2021-06-01/mappings/mapping_id. You need to specify an entire new mapping definition, so when we talk about updating the mapping definition, we really mean replacing it.

Other than that, updating a mapping definition is the same as creating one: the request body is the same, the response body is the same.

Delete a mapping definition

You delete a mapping definition by DELETEing it at https://mappings.us.stedi.com/2021-06-01/mappings/mapping_id. That’s all there is to it, really. You don’t need to provide a request body and the response will be empty as well.

List mapping definitions

You retrieve a list of all your mapping definitions by GETting it from https://mappings.us.stedi.com/2021-06-01/mappings.

GET https://mappings.us.stedi.com/2021-06-01/mappings HTTP/1.1 "Authorization: ${STEDI_API_KEY}"

The response has a field mappings which contains a list with mapping definitions.

HTTP/1.1 200 OK
Content-Type: application/json
{}