API docs by Redocly

Elm API (1.0.0)

Download OpenAPI specification:Download

Contact: hello@getelm.co Terms of Service

Introduction

We’ve designed the elm API to give FMCG brands and third parties easier access to their key sales data. See more info below on how to fetch data from the elm API.

Note on Data Freshness

We work hard to keep our data fresh and accurate. Our system undergoes a daily data synchronisation process with all retailer connections to ensure that our dataset accurately reflects retroactive changes made by these retailers. This synchronisation typically covers the previous 4-7 days, depending on the specific data processing practices of each retailer.

Retailers often apply these backdated modifications to their data. Daily updates are required to ensure the most up-to-date and precise historical data, which reflects what is available on the retailer's own platform.

In practical terms, this means that if you were to retrieve sales totals for a Sunday on a Monday, the total for that Sunday may change when viewed on subsequent days such as Tuesday, Wednesday, or Thursday.

To accommodate these retailer-driven data changes effectively, we recommend including a request for data that spans approximately the last seven days in every API call. By doing so, you can ensure access to the most current information. When adding this data to your database, you can:

  1. Keep all versions but use the most recent data.
  2. Clear the previous day's data before adding new results.

This ensures 100% accuracy when handling retroactive changes, avoiding potential discrepancies of up to around 1% in historical sales totals if these practices are not followed.

API Keys

This API relies on an API key for authentication. To generate/access your API key please make sure that you have admin level access to your Elm account.

To generate your API key:

  • Log in to your account and, navigate to Account Settings
  • Visit the API tab
  • On this page you will be able to generate an API key, view your key, and regenerate your key if your existing one is lost or exposed.

Please note that API keys are sensitive pieces of information and as such should be kept secret, like a password.

Authentication

Once you have your API key, you can use it for authentication by including it in the authorization header of your requests.

Headers:

Authorization: Token <your token>

Example request

This request can be used to test your connection to the API. A successful request and authorization will return {"success":true}

curl --request GET \
  --url https://api.getelm.co/api/test/ \
  --header 'Authorization: <your token>'

Test your connection

Test that you are correctly connecting to the API and return a success or error message accordingly.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "success": true
}

List

Get available retailers

This endpoint returns a list of the retailer connections that a user has access to in their elm account. To add further retailers/customers please visit the “Manage Connections” section of your elm dashboard.

Authorizations:
ApiKeyAuth
query Parameters
type
required
string
Value: "retailers"
Example: type=retailers

Returns list of available retailers

Responses

Response samples

Content type
application/json
[
  • "amazon",
  • "sainsburys",
  • "tesco",
  • "shopify"
]

Get available metrics

This endpoint returns a list of the available metrics that can be pulled from each data set. This can vary depending on the data connection due to the granularity of data available for each retailer.

Authorizations:
ApiKeyAuth
query Parameters
type
required
string
Value: "metrics"
Example: type=metrics

Returns list of available metrics by retailer

retailer
required
string
Example: retailer=sainsburys

Define retailer to return list of available metrics

Responses

Response samples

Content type
application/json
{
  • "retailer": "tesco",
  • "sku_metrics": [
    ],
  • "store_metrics": [
    ]
}

Get available SKU codes and filter names

This endpoint returns a list of the SKU codes and filter names that can be requested. To define filter names and to associate them with SKU codes please visit the "Product Settings" section of your elm dashboard.

Authorizations:
ApiKeyAuth
query Parameters
type
required
string
Value: "filters"
Example: type=filters

Returns list of available SKU codes and filter names by retailer

retailer
required
string
Example: retailer=sainsburys

Define retailer to return list of available SKU codes and filter names

Responses

Response samples

Content type
application/json
{
  • "sku": [
    ],
  • "skuProductName": [
    ],
  • "filter1": [
    ],
  • "filter2": [
    ],
  • "filter3": [
    ],
  • "filter4": [
    ],
  • "filter5": [
    ]
}

Data

Return data by SKU

Use the data by SKU endpoint to retrieve SKU level sales data by retailer for the selected timeframe. This is best used when looking for top level sales information, rather than requiring sales by store data - which is on a weekly basis.

Authorizations:
ApiKeyAuth
query Parameters
type
required
string
Value: "sku"
Example: type=sku

Return data at a SKU or store level

retailer
required
string
Example: retailer=sainsburys

Name of retailer to pull data from. Use /list to list available retailer options.

Note: retailer=all applies only to SKU level data. Using retailer=all is equivalent to viewing the Sales Summary charts where retailer=sainsburys is equivalent to viewing the charts in the Sainsbury's dashboard.

timeframe
required
string
Enum: "daily" "weekly" "monthly"
Example: timeframe=daily

Return data by week or day.

Note: Not all combinations of retailers and metrics will have access to daily data.

metric
required
string
Enum: "units" "revenue" "wastage" "stock" "lost_sales" "availability" "unit_ros" "value_ros" "ranged_stores" "stores_selling" "stores_with_stock"
Example: metric=revenue

Which metric(s) should be returned. Multiple metrics can be returned in one request when separated by a comma. E.g. metric=revenue,units,stock

Note: Not all metrics will be available depending on retailer/timeframe/type selections. In addition, multiple metrics must be separated by a single comma. Spaces and other characters can prevent the data from returning correctly.

datefrom
required
string
Example: datefrom=2022-08-13

Date from which to begin pulling data in the format YYYY-MM-DD

dateto
required
string
Example: dateto=2022-10-18

Date on which to end pulling data in the format YYYY-MM-DD

comparison
string
Enum: "period" "year"
Example: comparison=period

Returns an extra column for each metric selected with the value percentage change between the current period/year and the previous period/year.

'Period' refers to the value for the preceding timeframe. I.e. if the current timeframe is 'week', the 'period' value will be the value for the previous week.

'Year' refers to the value for the same timeframe in the previous year. I.e. if the current timeframe is 'week', the 'year' value will be the value for the same week in the previous year.

filter
string
Default: "sku"
Enum: "sku" "filter1" "filter2" "filter3" "filter4" "filter5"
Example: filter=filter2

Define whether the results should be filtered by SKU or product filters (optional). This parameter is required if you would like to return data for a specific SKU or filter.

Note: When selecting filters, the filter names will be returned in place of SKU codes. A list of available SKU codes and filter names can be accessed through the /list path.

viewby
string
Examples:
  • viewby=334 - with filter=sku
  • viewby=Multi pack - with filter=filter1

SKU code used to filter data down to a specific SKU or filter. Requires the filter parameter to be set to 'sku' or a specific filter.

Note: Filter names are case sensitive.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Return data by Store

Use the data by Store endpoint to retrieve sales and other data points grouped by SKU and store ID / name. This data set is updated on a weekly basis. This data is often used when more granular data is required for tasks like field team work.

Authorizations:
ApiKeyAuth
query Parameters
type
required
string
Enum: "sku" "store"
Example: type=sku

Return data at a SKU or store level

retailer
required
string
Example: retailer=sainsburys

Name of retailer to pull data from. Use /list to list available retailer options.

Note: retailer=all applies only to SKU level data. Using retailer=all is equivalent to viewing the Sales Summary charts where retailer=sainsburys is equivalent to viewing the charts in the Sainsbury's dashboard.

timeframe
required
string
Enum: "weekly" "monthly"
Example: timeframe=weekly

Return data by week

metric
required
string
Enum: "units" "revenue" "wastage" "stock" "lost_sales"
Example: metric=wastage

Which metric(s) should be returned. Multiple metrics can be returned in one request when separated by a comma. E.g. metric=revenue,units,stock

Note: Not all metrics will be available depending on retailer/timeframe/type selections. In addition, multiple metrics must be separated by a single comma. Spaces and other characters can prevent the data from returning correctly.

datefrom
required
string
Example: datefrom=2022-08-13

Date from which to begin pulling data in the format YYYY-MM-DD

dateto
required
string
Example: dateto=2022-10-18

Date on which to end pulling data in the format YYYY-MM-DD

comparison
string
Enum: "period" "year"
Example: comparison=period

Returns an extra column for each metric selected with the value percentage change between the current period/year and the previous period/year.

'Period' refers to the value for the preceding timeframe. I.e. if the current timeframe is 'week', the 'period' value will be the value for the previous week.

'Year' refers to the value for the same timeframe in the previous year. I.e. if the current timeframe is 'week', the 'year' value will be the value for the same week in the previous year.

filter
string
Default: "sku"
Enum: "sku" "filter1" "filter2" "filter3" "filter4" "filter5"
Example: filter=filter2

Define whether the results should be filtered by SKU or product filters (optional). This parameter is required if you would like to return data for a specific SKU or filter.

Note: When selecting filters, the filter names will be returned in place of SKU codes. A list of available SKU codes and filter names can be accessed through the /list path.

viewby
string
Examples:
  • viewby=334 - with filter=sku
  • viewby=Multi pack - with filter=filter1

SKU code used to filter data down to a specific SKU or filter. Requires the filter parameter to be set to 'sku' or a specific filter.

Note: Filter names are case sensitive.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Actions

Get all actions by retailer

This endpoint returns a list of all active actions, insights and alerts as set out in your elm account along with accompanying information by retailer for a given week. This data set is often used as the first step in a successful field visit, for example, as it outlines problem stores.

Note: Actions are refreshed weekly and so please plan your API requests accordingly. We’d recommend pulling through actions on a Tuesday.

Authorizations:
ApiKeyAuth
query Parameters
retailer
required
string
Example: retailer=sainsburys

Name of retailer to pull data from. Use /list to list available retailer options.

Note: retailer=all applies only to SKU level data. Using retailer=all is equivalent to viewing the Sales Summary charts where retailer=sainsburys is equivalent to viewing the charts in the Sainsbury's dashboard.

Responses

Response samples

Content type
application/json
[
  • {
    }
]