API Reference

API Reference

Welcome to Memo. By integrating with Memo, you’ll be able to see the actual engagement data on editorial content from thousands of marquee publishers. Below you will find comprehensive documentation for the Memo API, containing everything you need in order to integrate.

The Memo API follows the JSON API spec. It uses HTTP response codes to indicate successful calls and API errors. All responses, including errors, are returned in JSON.

Authentication

In order to successfully interact with the API, you need an API key, which will be provided by your Customer Success Manager.

Any request made without the appropriate authentication headers will fail. Do not share your API keys in publicly accessible areas like client-side code, GitHub, documentation, etc.

Below is a table listing the expected headers and values.

HeaderValue
x-api-keyAs provided by Memo

Errors

Memo uses HTTP response codes to indicate whether an API request has succeeded or failed. Below is an overview of the different responses you can expect:

2xx: Codes in this range indicate that the request was successful

  • 200: The request was successful
  • 201: The request was successful and the new entity was created

4xx: Codes in this range indicate that there was an error that failed based on what was provided by the client.

  • 400: Malformed request
  • 403: An action you’re attempting to take is not allowed for the user token provided
  • 404: Resource you were looking for does not exist
  • 422: A parameter was missing or was incorrect
  • 429: You’ve exceeded the API rate limit. We recommend waiting and retrying using an exponential backoff for your requests. You may also get a 429 trying to reach an endpoint that is not provisioned for your account.

5xx: Codes in this range mean that there was an error with Memo’s servers.

  • 500: Something unexpected went wrong on Memo’s end. If you are seeing this on report_data, try a smaller request limit.
  • 503: The request timed out. In many cases retrying will work, we encourage building in retry logic with an exponential backoff for any automated API calls.

There are many different reasons why the Memo API could raise an error. We encourage writing software that gracefully handles these API error responses. If you run into errors that you cannot recover from via retry please report them to your Customer Success Manager. Please be sure to include the following when reporting any problems: time(s) the request was made, exact URL or request including all parameters, HTTP response code, error message (if available), and the API key used.

Versioning

Any destructive changes to APIs will be versioned, followed by a deprecation period of the previous version. Structural changes, including removing fields, will be considered destructive. Adding a new field will not be considered a destructive change.

Rate Limits and Quotas

The following rate applies to all endpoint requests, not per endpoint.

  • 2 requests per second with a concurrency limit of 1
  • 100 Requests per day for v2 endpoints and 1000 / day for v3 endpoints.

Please contact your customer success manager if you believe you need to exceed these limits. As our data updates daily and no longer updates after 7 days, there are likely few scenarios where these limits would be approached.

Endpoints

Reports

The reports endpoint returns reference to all reports that your user token has access to. Our data is structured in a hierarchy from account to dashboard to report. A user typically has access to a single account. An account has one or more dashboards, which in turn has one or more reports (which we usually refer to as brands or competitors).

MethodGET
URIhttps://api.memo.co/v2/reports
ParametersNo input parameters are required on this endpoint.
Example requestcurl -X GET \
  https://api.memo.co/v2/reports \
  -H 'x-api-key: <your API key>'
Example response{
  "data": [
    {
      "account_id": "12-34-56",
      "account_name": "Account with One Dashboard",
      "dashboards": [
        {
          "dashboard_id": "12-34-56",
          "dashboard_name": "Dashboard 1",
          "reports": [
            {
              "report_id": "12-34-56",
              "report_name": "Report 1"
            }
          ]
        }
      ]
    },
    {
      "account_id": "12-34-56",
      "account_name": "Account With Multiple Reports",
      "dashboards": [
        {
          "dashboard_id": "12-34-56",
          "dashboard_name": "Single Report Dashboard",
          "reports": [
            {
              "report_id": "12-34-56",
              "report_name": "Report 2"
            }
          ]
        },
        {
          "dashboard_id": "12-34-56",
          "dashboard_name": "Dashboard with Competitors",
          "reports": [
            {
              "report_id": "12-34-56",
              "report_name": "Brand 1"
            },
            {
              "report_id": "12-34-56",
              "report_name": "Brand 2"
            },
            {
              "report_id": "12-34-56",
              "report_name": "Brand 3"
            }
          ]
        }
      ]
    }
  ]
}

Some accounts will have access to create reports on demand. This is an uncommon use case and API clients will need to speak with their Customer Success representative to enable this functionality.

MethodPOST
URIhttps://api.memo.co/v2/reports
Payloaddashboard_id (required)
The dashboard ID from reports endpoint
report_name (required)
Name for your new report. This may be an ID for your internal mapping purposes but helps to be human readable.
Response201: New Report Was Created
422: Required parameters missing or report name is non-unique
Example request  curl --location --request POST 'https://api.memo.co/v2/reports' \
   --header 'Content-Type: application/json' \
   --header 'x-api-key: <your API key>' \
   --data '{
   "dashboard_id": "<dashboard ID>",
   "report_name": "<report name>"
   }'

Report Data V3

The v3 report data endpoint returns readership data for all articles on a report for a range of date (up to 1 week). The date ranges always reflect when the articles were published, not the day when readership occurred; pulling a report for 01/01/2023 to 01/07/2023 will return the articles and readership data for all articles published between 01/01/2023 and 01/07/2023.

The most common pattern for calling this endpoint it to ask for the trailing 7 days of data a few times per day. For example on Jan 8, ask for Jan 1-Jan 7 data once in the morning and once in the evening. There will be very little change in this data throughout the day.

Some important notes on the structure and cadence of Memo readership data:

  • One report will return the articles for a single brand in your overall dashboard. If you have multiple brands in a competitive report dashboard you will need to call report_data once per brand and will see duplication if some articles exist in multiple brands.
  • Readership data is cumulative by URL and is not available segmented out by the date the readership occurred.
  • Readership data continues to collect and update daily for 7 days after being published so you will likely need to continue to collect on the same publish date for 7 days. After the 8th day this data will no longer update.
  • This endpoint returns a maximum of 5,000 records; date ranges with more articles will paginate.
  • If you see 500 errors please try requesting with a smaller limit. We may be generating a response payload that is too large for our CDN to pass through.
  • Readership data is updated daily, and is generally first available the morning 9AM ET the day AFTER an article was originally published. Requesting the same date range multiple times a day will generally return the same data. Once in the morning and once in the afternoon should per date should be more than enough.
  • Requesting a report for the current date will result in an error.
MethodGET
URIhttps://api.memo.co/v3/report_data
Parametersdashboard_id (required)
The dashboard ID from reports endpoint
report_id (required)
The report ID from reports endpoint
start_date (required)
Start of published date range of articles you want to retrieve data for in YYYY-MM-DD format 

notes:
– start date must be 0-7 days before end date
– MM/DD/YYYY format is also accepted but generally not preferred
end_date (required)
Start of published date range of articles you want to retrieve data for in YYYY-MM-DD format.

notes:
– end date must be yesterday or prior
– MM/DD/YYYY format is also accepted but generally not preferred
limit
Limit the number of articles you are getting back in a response. Use this or limit the date range if performance is a concern. Default is currently 5,000 but this may change without notice so build in paginating. Maximum is 5,000.
page
Page offset for paginated responses.
Responseurl
Canonical URL of the article
headline
Headline of the article (at the time of collection)
quote
Extract of article, generally truncated quote that matches the article text leading to its inclusion in this report. Can be blank.
published_date
Published date of article in UTC
readership
Count of users who read this article within the first 7 days of it being published
data_type
Data source: direct readership or a predicted value. 2
average_engaged_time
Average number of seconds spent on this article over the first 7 days of being published 1
authors
Array of authors
publisher_name
Name of site article was published on
publisher_region
Publisher type: local or national
topic
Topic article was assigned to
mrv
Memo Readership Value 2
tags
Custom tag(s) assigned to article.2
article_sentiment
Overall sentiment of the article 2
brand_sentiment
Sentiment of the brand in the article 2
referring_domains
Top 10 referring domains and associated metrics1,2
device_mobile_views
Page views attributed to mobile users 1,2
device_desktop_views
Page views attributed to desktop users 1,2
device_tablet_views
Page views attributed to tablet users 1,2
medium_search_views
Page views attributed to search referrals 1,2
medium_social_views
Page views attributed to social referrals 1,2
medium_direct_views
Page views attributed to direct (or email) referrals 1,2
medium_internal_views
Page views attributed to referrals on the same publisher 1,2
medium_other_views
Page views attributed to other or unknown referrals 1,2
benchmark_bucket
How article readership compares to the publisher’s average performance. Possible values are “below”, “slightly below”, “meets”, “slightly above”, and “above”. 1,2
1) not available on all articles
2) add-on feature available to some accounts
Example requestcurl --location --request GET \
  'https://api.memo.co/v3/report_data \
?dashboard_id=<dashboard ID> \
&report_id=<report ID> \
&start_date=2023-01-01' \
&end_date=2023-01-07' \
--header 'x-api-key: <your API key>'
Example response 
"data": [
   {
      "attributes": {
         "url": "https://memo.co/12345.html",
         "headline": "Example Headline",
         "published_date": "2023-01-01",
         "readership": 100,
         "average_engage_time": 100,
         "authors": [
            "Joe Memo"
         ],
         "publisher_name": "Publisher Name",
         "publisher_region": "Uncategorized",
         "topic": "Example Topic",
         "mrv": 100,
         "tags": [
          "Sample Tag"
         ],
         "article_sentiment": "Neutral",
         "brand_sentiment": "Positive",
         "referring_domains": [
           {
               "type": "search",
               "views": 100,
               "domain": "search.com",                            
                     "uniques": 99
            }
         ]
         "device_mobile_views": 100,
         "device_desktop_views": 100,
         "device_tablet_views": 100,
         "medium_search_views": 100,
         "medium_social_views": 100,
         "medium_direct_views": 100,
         "medium_internal_views": 100,
         "medium_other_views": 100,
         "benchmark_bucket": "above"
      }
   ],
   "next": "https://api.memo.co/v3/report_data...&page=2"
}

Articles

The articles endpoint allows users to directly add new articles to a report. This endpoint is not available to all API customers.

MethodPOST
URIhttps://api.memo.co/v1/articles
Payloaddashboard_id (required)
The dashboard ID from reports endpoint
report_id (required)
The report ID from reports endpoint
url (required, or urls)
URL we expect it to be canonical with no URL params unless those are part of it being canonical. Passing in a non-canonical URL may result in poor results. Field is not required if passed in as an array of URLs (below)

urls (required, or url)
As above but can pass in an array. A maximum of 100 URLs can be processed in one request.
Response200 (single URL requests): Memo is already tracking the URL. The data will be returned in the response. Note response codes are slightly different when calling in bulk.

200 For bulk requests (urls parameter in the payload) we will return a 200 with different nodes in the response so observe the response body for URLs that were invalid or in different states:

{
"articles": [
{
"url": "https://unavailableurl.com/test",
"message": "Article is not available for tracking"
},
{
"url": "https://inprogressurl.com/working",
"message": "Data collection is still in progress"
}
],
"invalid_urls": [
"Not URL format",
"https://top-level-domain.com/",
"https://ct.moreover.com/click?this-is-a-redirect",
]
}
201: Memo is not tracking this URL, but it will be added and available at a later time.
410: We have tried and are unable to track this article.
422: A parameter in the post is invalid. This can also refer to a specific URL being untrackable, such as a social media post or an international article.
Example request  curl --location --request POST 'https://api.memo.co/v1/articles' \
   --header 'Content-Type: application/json' \
   --header 'x-api-key: <your API key>' \
   --data '{
   "dashboard_id": "<dashboard ID>",
   "report_id": "<report ID>",
   "url": "https://app.memo.co"
   }'

– OR –

  curl --location --request POST 'https://api.memo.co/v1/articles' \
   --header 'Content-Type: application/json' \
   --header 'x-api-key: <your API key>' \
   --data '{
   "dashboard_id": "<dashboard ID>",
   "report_id": "<report ID>",
   "urls": ["https://app.memo.co/1", "https://app.memo.co/2"]
   }'

Some notes on usage:

  • Generally speaking, Memo supports article readership in the U.S. (some international domains so those may be rejected) If you add non-articles like landing pages, category pages, social media links, etc. you may be adding activity that we do not currently track.
  • For best results, follow URLs until there are no 301 redirects and you can deliver a clean canonical URL to us for tracking. We do this on our end as well but this will make it easier for you to find the articles previously sent in to Memo. Non-canonical URLs or URLs that are redirected may result in poor results and you may have difficulty finding the URL in your data lookup that you previously requested.
    • Important: For the reasons mentioned above we will not track articles that appear to be redirects from a service like LexisNexis.
  • If a URL is redirected after you have added it, we will not keep track of its new URL. You will have to track it as a new article if you want to see readership on it.
  • If calling with an array of URLs, the response is given in an array with an array of message containing either status of each URL or readership data.
  • Articles that were published more than a week ago are far more likely to be unavailable.
  • If readership returned is empty in a 200 response, it may mean we are aware of the article but have not received any data on it yet.
  • No more than 100 urls can be processed in a single request.
  • Once you have added a URL and are looking for the data you will need to filter by the published date of the URL in the report_data endpoint. Published dates on the article may change over time (example evergreen articles) so we keep the first observed published date on any particular URL.
  • Response type is slightly different when processing in bulk. If any URLs are successful, they will be returned with a 200 and an array of the status of each URL in your request.