Reporting

Creating your Reporting API User

• Go to Accounts > Clientarea accounts
  
• Create a new Reporting API User by clicking Add New
  
• Complete the API User details:
  • Main details block
    
    • Add a Name
    • Select Is API User
    • Select the Client name
  • Reporting block
    
    • Select Permission access to report
    • Select Anonymise data if you do not want the staff full names to appears in the data
    • Click Submit
    • You can now Add Reports to assign to your API user
      
    • Start typing the report name to select from the dropdown
      
    • Repeat until you have added all the reports required
      
    • To hide questions from the API data
      • Click on Questions
        
      • Click on Add New
      • Select the questions from the list
        
      • Click on OK
      • Click on Close
  • Press Submit to confirm

Important: The API User will only be able to retrieve data from reports that have been assigned to it.

Retreiving your API Key

From the main Clientarea Accounts User list

• Click Manage against your API User.
  
• Your unique API key will be displayed within the account.
  
• Copy the Key. This will be used as the authentication token when making requests to the Reporting API.

Security: Your API key should be stored securely and should only be shared with authorised systems or developers responsible for your integration.

Creating your Endpoint URL

The Reporting API endpoint is:

https://subdomain.staffed.it/reporting/api/get-data/{report-id}
https://subdomain.staffwise.app/reporting/api/get-data/{report-id}
https://subdomain.retailwise.app/reporting/api/get-data/{report-id}

Replace the following values:

subdomain
The unique subdomain of your Staffwise system.

{report-id}
The unique ID of the report you wish to retrieve data from.

Finding your Report ID

Your Report ID can be found in either of the following locations.

• Option 1 - Reporting API User
  • Go to Accounts > Clientarea accounts
    
  • Click Manage against the relevant API User.
    
  • The Report ID is displayed in the first column.
    
• Option 2 - Reporting
  • Go to Reporting > View Reporting
    
  • The Report ID is displayed in the second column of the report list.
    

JSON request for retrieving submissions

Send the request body in JSON format to the Reporting API endpoint.

Request Body

{
  "token": "your-token-here",
  "exportFormat": 1,
  "dateStart": "2021-03-31",
  "dateStop": "2021-04-30"
}

Request Parameters

Export Formats

0 - Standard CSV
Exports multiple-value questions as a single row.

1 - Fixed-column CSV
Exports multiple-value questions as a single row with a static number of columns. This is typically useful where survey logic is being used and a consistent export structure is required.

2 - Multi-row CSV
Exports multiple-value questions across multiple rows.

API Responses

The Reporting API uses standard HTTP response codes to indicate the result of each request.

200 - Success

The request was successful and the CSV output will be returned.

400 - Incorrect Request

The request could not be processed.

Where a specific issue can be identified — such as an invalid exportFormat or incorrect date — an error message will be returned providing further information.

401 - Authentication Error

Authentication was unsuccessful.

This may occur where:

• No API token has been provided
• The API token is invalid
• The Reporting API User is inactive

403 - Access Denied

The API User does not have permission to access the requested report.

This may occur where:

• The report has not been assigned to the API User
• The Report ID is incorrect
• The report no longer exists