API units: 5 or 25. A page of up to 100 records uses 5 units. A page over 100 records uses 25 units. The default page size is 1,000, so a request without a page size uses 25 units.

Retrieves raw analytics events for the given service over the given timeframe. There are several types of analytics event, identified via the type property in each event:

Event type	type property	description
Page view event	pageView	Written on every page hit. Includes properties identifying the page that has been hit.
Journey complete event	isUserComplete	Written when the journey is completed, either because the user has hit an Acknowledgement Page or has completed all tasks on the Task List.
Page action execution event	pageAction	Written when a Page Action is executed. Includes the ID of the action and response code from the action execution.
Field tagging event	taggedFieldsSet	Written when a page is submitted by the user containing data for tagged fields. You can tag fields for analytics data collection using the Analytics tab in Service Settings. The event includes the ID and value of each tagged field that was set by the user on the page.

Data can be returned in JSON or CSV format. The columns in the CSV are fixed; not all values will be set for all events as some columns are specific to one event type.

Use the query parameters to filter the results by event date/time. Results are paginated, meaning the API endpoint will provide the first page of results along with the number of pages. Your application can then call the endpoint again to retrieve subsequent results pages.

Endpoint and parameters

GET /api/analytics-events/{libraryId}/{serviceId}

Parameter	Description	Mandatory
libraryId	The ID of the library of the service from which to retrieve analytics events	yes
serviceId	The service ID of the service from which to retrieve analytics events	yes

Query parameters

Parameter	Description	Mandatory
format	The output format to use in the response body, set to json or csv	yes
fromDate	The first event date to return data for (inclusive), in the format yyyy-mm-dd	yes
toDate	The last event date to return data for (inclusive), in the format yyyy-mm-dd	yes
hour	Restrict the result to one completed hour (0–23). Use only when fromDate and toDate are the same. For today, the hour must be earlier than the current hour. If omitted for today, Govforms returns data only up to the start of the current hour.	no
page	The page of results to fetch. If omitted, page 1 is assumed. The response body will include the number of pages to fetch; if over 1 then the endpoint should be called again with this parameter set to each subsequent page number to retrieve all result pages.	no
pageSize	Number of results per page, from 1 to 1000. Defaults to 1000; larger values are capped at 1000.	no
submissionRef	If specified, only events for the specified submission reference will be returned.	no
csvHeader	If format is set to csv, this parameter controls the header row to output. Set to on to include field names in the header row. Set to none to not include a header row in the output. Defaults to on.	no
csvHeaderFields	If format is set to csv, optionally set this to specify which fields should be included in the output, separated by commas. The provided values are compared against the CSV header titles for each field and so depend upon the csvHeader setting. The provided field columns will always be present in the order specified and no additional columns will be added.	no
excelMode	If format is set to csv, set this to on to wrap all values that are under 200 characters in ="value" to prevent Excel from attempting to auto-transform numbers and dates. For raw CSV feeds not intended for display in Excel, set to off. Defaults to off.	no

Authentication: send GovformsApiKey <key-id>:<key-secret> in the Authorization header. Substitute credentials from your secrets manager; never copy a live key into documentation, source control or logs.

Examples

Request headers

Header name	value
Authorization	GovformsApiKey <key-id>:<key-secret>

Request URL

GET https://qa.cloud.govforms.uk/api/analytics-events/demo-library/demo-service-1?format=json&fromDate=2023-03-18&toDate=2023-03-18

  Response headers

Header name	value
Content-Type	application/json

Response body

{
  "totalResults": 2,
  "totalResultsPages": 1,
  "resultsPage": 1,
  "results": [
    {
      "submissionId": "X6GY-FDLJ-P8A2",
      "userId": "anon-ff607409-34f4-4562-8001-acd8de37c1ad",
      "userEmail": null,
      "timestamp": "2023-03-18T14:57:53.256+00:00",
      "type": "pageView",
      "pageId": "bfeee0d9-13ca-4c69-aafc-486d93722bh5",
      "pageIdx": 3,
      "pageTitle": "About you",
      "pageType": "contentPage",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41"
    },
    {
      "submissionId": "X6GY-FDLJ-P8A2",
      "userId": "anon-ff607409-34f4-4562-8001-acd8de37c1ad",
      "userEmail": null,
      "timestamp": "2023-03-18T14:58:06.512+00:00",
      "type": "taggedFieldsSet",
      "taggedFieldData": {
        "firstName": "John",
        "gender": "male"
      },
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41"
    }
  ]
}

 

CSV mode example:

Request URL

GET https://qa.cloud.govforms.uk/api/analytics-events/demo-library/demo-service-1?format=csv&fromDate=2023-03-18&toDate=2023-03-18

  Response Headers

Header name	value
Content-Type	text/csv
Govforms-Total-Results	2
Govforms-Total-Results-Pages	1
Govforms-Results-Page	1

Response Body

"submissionId","userId","userEmail","timestamp","type","pageId","pageIdx","pageTitle","pageType","userAgent","taggedFieldData-fieldId","taggedFieldData-fieldValue","isUserComplete","actionId","isSuccess","responseCode","fieldFailure-fieldId","fieldFailure-fieldLabel","fieldFailure-iteration","fieldFailure-fieldPartId","fieldFailure-errorMsg","fieldFailure-fieldValue"
"X6GY-FDLJ-P8A2","anon-ff607409-34f4-4562-8001-acd8de37c1ad","","2023-03-18T14:57:53.256+00:00","pageView","bfeee0d9-13ca-4c69-aafc-486d93722bh5","3","About you","contentPage","Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41","","","","","","","","","","","",""
"X6GY-FDLJ-P8A2","anon-ff607409-34f4-4562-8001-acd8de37c1ad","","2023-03-18T14:58:06.512+00:00","taggedFieldsSet","","","","","Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.41","firstName|gender","John|male","","","","","","","","","",""

     

---