If the totals, day labels, or delivery counts you get from the reports API look different from what you see on your Dashboard, your data is not wrong. The two are measured in slightly different ways. This article explains the three reasons the numbers differ, and tells you which value to use for each question.
The short version
The Dashboard and the API cover the same date range, but they can label and group it differently.
Three things cause the differences: your account timezone, the fact that each object in the payload measures a different thing, and the way the score counts each contact only once.
For the total responses and score of a period, use the
lastobject in the API response. It always matches the Dashboard.
Reason 1: Timezone and day labels
When you filter by date, both the Dashboard and the API use your account's timezone to set the start and end of the range. So a filter for a single day covers the same window in both places.
Inside the API response, the trend array groups each day by UTC, not by your account timezone. If your timezone is not UTC, one day in your local time can span two UTC dates. When that happens, a single day you asked for can come back as two rows in trend, and the second row can carry the next day's date.
Here is what that looks like for an account in US Pacific time (UTC minus 7) that filters for a single day:
In UTC, that local day runs from 07:00 on the day you picked to 07:00 the next day.
The evening portion of your local day falls on the next UTC date.
So
trendreturns two rows, and the later one is labeled with the following day.
The trend values accumulate across the range, so the last (latest dated) row holds the complete total for your filter. This is why the row that matches your Dashboard can appear under the next day's date.
To avoid the confusion entirely, read the total for your range from the last object. It is the running total for the whole range you requested, and it always equals the Dashboard total for the same filter.
Reason 2: Each object measures a different thing
The reports payload contains several objects, and they are not different views of the same number. They answer different questions.
trend and last (the score block) count survey responses by the date each response was received. This is what the Dashboard score, promoters, passives, and detractors are based on.
deliveryStats describes the surveys that were sent in the date range, not the responses received. Its fields are:
totalCount: surveys sent in the range.opened: how many of those were opened.responded: how many of those have an answer, whenever the answer arrived.optedOut: how many opted out.isBounced: how many bounced.
Because the score counts responses by when they were received and deliveryStats.responded counts surveys by when they were sent, the two rarely match exactly:
For an older, settled day, they are usually close, because almost every survey sent that day has already been answered.
For a recent day,
respondedis often higher than the score total, because surveys sent that day are still being answered on later days. Those later answers count towardresponded(the survey was sent in your range), but not toward the score for that day (the response arrived on a different day).
The reverse also happens: a response received in your range for a survey that was sent earlier adds to the score, but not to deliveryStats.responded.
deliveryStats also excludes imported feedback (responses to surveys that were not sent through Retently), while the score and trend include it.
Reason 3: The score counts each contact once
The score, and the promoter, passive, and detractor counts, consider only the last response from each contact. If a contact answered more than once in the range, only their most recent answer is counted.
deliveryStats.responded does not do this. It counts each answered survey. So a contact who answered more than once adds to responded, but only once to the score.
For most single day ranges this makes no difference, because few contacts answer twice in one day. On longer ranges it can widen the gap between the score total and deliveryStats.responded.
Which number should I use?
Total responses and score for a period: use the
lastobject, or read it from the Dashboard. They match.The trend over time: use the
trendarray, and read each day label as a UTC date if your account is not on UTC.Surveys sent, open rate, response rate, opt outs, bounces: use
deliveryStats. These are anchored to when surveys were sent.
Quick FAQ
The API shows two days when I filtered for one. Why?
Your account timezone is not UTC, so your local day spans two UTC dates and the trend splits it. The last row is the cumulative total for your range, and it matches the Dashboard. Use last for the single total.
The day that matches my Dashboard is labeled with the next date. Is the data wrong?
No. The trend labels days by UTC, and the cumulative total for your local day lands on the later UTC date. The value is correct, only the label is shifted by your timezone offset.
deliveryStats.responded does not equal my promoters plus passives plus detractors. Why?
They measure different things. The score counts responses by the date they were received, and counts each contact once. deliveryStats.responded counts answered surveys by the date they were sent. On recent days responded is usually higher, because sent surveys are still being answered.
Does imported feedback affect this?
Imported feedback counts toward the score and trend, but not toward deliveryStats, because those surveys were not sent through Retently.
Related