API Reference
Welcome to Memo. By integrating with Memo, you’ll be able to see the actual engagement data on editorial content from hundreds 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.
| Header | Value |
| x-api-key | As 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 using an exponential backoff for your requests.
5xx: Codes in this range mean that there was an error with Memo’s servers.
- 500: Something unexpected went wrong on Memo’s end
- 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.
- 1 request per second with a burst limit of 10
- 100 Requests per day
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).
| Method | GET |
| URI | https://api.memo.co/v2/reports |
| Parameters | No input parameters are required on this endpoint. |
| Example request | curl -X GET \ |
| Example response | { |
Report Data
The report data endpoint returns readership data for all articles on a report for a single date. This date always reflects when the articles were published, not the day when readership occurred; pulling a report for 01/01/2021 will return the readership data for all articles published on 01/01/2021.
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.
- 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.
- To retrieve data on articles published across a range of days, simply call this endpoint once for each published date. To access a large range of historical data it may be more efficient to create an export from the Memo user interface.
- Readership data is updated daily, and is first available the morning 9AM ET AFTER an article was originally published. Requesting a report for the current date will result in a 409 error.
| Method | GET |
| URI | https://api.memo.co/v2/report_data |
| Parameters | dashboard_id The dashboard ID from reports endpoint |
| “ | report_id The report ID from reports endpoint |
| “ | published_date Published date of articles you want to retrieve data for in MM/DD/YYYY format (note: date must be yesterday or prior) |
| Response | url Canonical URL of the article |
| “ | headline Canonical headline of the article (at time of collection) |
| “ | brand_in_headline Indicates whether the brand keyword in the report in the headline of the article. Boolean. |
| “ | topic Topic article was assigned to (optional) |
| “ | publisher Name of site article was published on |
| “ | author Array of authors |
| “ | 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 |
| “ | average_engaged_time Average number of seconds spent on this article over the first 7 days of being published (Not available for all articles) |
| Example request | curl --location --request GET \ |
| Example response | { |