Query the Reporting API

The Reporting API uses the OData 4.0 protocol. For more information, see OData.org and Oasis: OData Version 4.0 Protocol. This topic describes the query string parameters and filter expressions you can use to customize your queries to return the required data.

Based on your region, use one of the following URLs to connect to the Reporting API.

Region

Reporting API URL
Australia https://au-reporting.promapp.io/odata

United States

https://us-reporting.promapp.io/odata

Europe

https://eu-reporting.promapp.io/odata

Canada

https://ca-reporting.promapp.io/odata

UAE https://ae-reporting.promapp.io/odata

Filtering data

To add a filter to an OData URL, add $filter= to the end of the endpoint name.

Example URL Description
https://au-reporting.promapp.io/odata/processes?$filter=PublishState eq 'Published' Returns all published processes.
https://au-reporting.promapp.io/odata/processes?$filter=PublishState eq 'Published' and ProcessGroupName eq 'Finance' Returns all published processes in the 'Finance' process group.
https://au-reporting.promapp.io/odata/Incident?$filter=Status eq 'New' Returns all newly created incidents, so you can action them.
https://au-reporting.promapp.io/odata/Incident?$filter=Priority eq 'High' and PortfolioName ne 'Supplier issue' Returns all incidents filtered by High priority for all portfolio names except 'Supplier issue'.
https://au-reporting.promapp.io/odata/Incident?$filter=PortfolioName ne 'Supplier issue' Returns all incidents filtered by the portfolio name except 'Supplier issue'.
https://au-reporting.promapp.io/odata/ProcessViews?filter=ViewDate gt 2023-01-01T00:00:00Z Returns all process views after January 1st 2023.

You must use the appropriate notation for different data types with filter expressions.

  • String values must be delimited by single quotation marks.
  • Numeric values require no delimiters.

Filter operation

Term used
Equal eq
Select a range of values lt, gt
And and
Or or
Less than lt
Greater than gt
Greater than or equal to ge
Less than or equal to le
Different from (not equal) ne
Ends with endswith
Starts with startswith
Substring of substringof
Length length
Index of indexof
Replace replace
Substring substring
To lower tolower
To upper toupper
Trim trim
Concatenate concat
Day day
Month month
Year year
Hour hour
Minute minute
Second second
Round round
Floor floor
Ceiling ceiling

Query string parameters

System query options are query string parameters that control the amount and order of the data returned for the resource identified by the URL. The names of all system query options are prefixed with a dollar ($) character.

You must follow the rules described in the following table when using query string parameters in your GET requests.

Resource path

Valid parameters
Contains a single entity, a complex type instance, or a collection of complex type instances.
  • $expand
  • $select
Contains a collection.
  • $filter
  • $count
  • $orderby
  • $skip
  • $top
Contains a collection of entities.

  • $expand

  • $select
Ending in /$count.

$filter
Not ending in /$count or /$batch. $format

You can use the following query string parameters:

Query string parameter

Description

Example URL
$count Returns a count of the records in the response. https://au-reporting.promapp.io/odata/Incident/$count
$expand Specifies the related resources to be included in line with retrieved resources. Only navigation properties can be expanded. https://au-reporting.promapp.io/odata/Incident?$expand=IncidentFields
$filter Filters a collection of resources that are addressed by a request URL. For a list of common expressions, see Filtering data. https://au-reporting.promapp.io/odata/Incident?$filter=Status eq 'New'
$orderby Returns resources in a particular order. https://au-reporting.promapp.io/odata/IncidentAction?$orderby=CreatedDate
$select Returns a specific set of properties for each entity or complex type. https://au-reporting.promapp.io/odata/IncidentAction?$select=CreatedDate,ActionType
$skip Returns the number of items in the queried collection that are to be skipped and not included in the result. https://au-reporting.promapp.io/odata/IncidentAction?$skip=30
$top Returns the number of items in the queried collection to be included in the result. https://au-reporting.promapp.io/odata/IncidentAction?$top=1

Expanding and selecting properties

To expand the collection fields, use the $expand string parameter.

For example:

  • https://au-reporting.promapp.io/odata/Incident?$expand=IncidentFields
  • https://au-reporting.promapp.io/odata/Incident?$expand=IncidentActionPlans
  • https://au-reporting.promapp.io/odata/Incident?$expand=IncidentActions
  • https://au-reporting.promapp.io/odata/Incident?$expand=IncidentInvestigations

To select specific properties, use the $select string parameter.

For example: https://au-reporting.promapp.io/odata/IncidentAction?$select=CreatedDate,ActionType

Ordering the results

To order the returned results by a particular field, use the $orderby string parameter.

For example: https://au-reporting.promapp.io/odata/IncidentAction?$orderby=CreatedDate desc

Status codes

The API returns a status code in the response which can help you troubleshoot in case of errors.

Status

Code

Description
200 OK Request was successful.
400 Bad Request The request is not in the correct format. For more information, see the error message returned by the API.
403 Forbidden There is an authentication error. Verify if you are using a valid authentication token or credentials.
404 Not found The requested resource does not exist. Verify if you have entered the correct endpoint name.
405 Not allowed The requested resource action is not allowed. For example: This error might be caused due to a missing required parameter or incorrect syntax.
500 Internal Server Error The server has encountered an unexpected condition that does not allow successful parsing of the request.

For more information or if you need support, contact Nintex Support.

Example: Querying using Postman

You can use Postman to send GET requests to the Reporting API and receive the JSON data.

Before you begin

Retrieve data using Postman

  1. Open the Postman application and open a new HTTP request.
  2. Click the Authorization tab.
  3. From the TYPE drop-down list, select Bearer Token.
  4. In the Token field, paste the API Key. For more information, see Create API Key.

  5. Ensure you have selected the GET method and then type the Query in the field.

    6. Based on your region, use one of the following URLs to connect to the Reporting API.

    Region

    Reporting API URL
    Australia https://au-reporting.promapp.io/odata

    United States

    https://us-reporting.promapp.io/odata

    Europe

    https://eu-reporting.promapp.io/odata

    Canada

    https://ca-reporting.promapp.io/odata

    UAE https://ae-reporting.promapp.io/odata

    For example:

    • https://au-reporting.promapp.io/odata/Incident: Returns the summary of the latest status for all incidents recorded in Nintex Process Manager.
    • https://au-reporting.promapp.io/odata/processes: Returns a summary of the latest process data in Nintex Process Manager.

    • https://au-reporting.promapp.io/odata/Incident?$filter=Priority eq 'High' and
      Status Ne 'Deleted'&$expand=IncidentFields&$orderby=ReportedDate      : Returns the summary of the latest status for all incidents recorded in Nintex Process Manager with the following conditions applied:

      • Filter by High Priority
      • Exclude Deleted incidents
      • Order by Reported Date
      • Expand IncidentFields collection fields

    • https://au-reporting.promapp.com/odata/processes?$filter=PublishState eq 'InProgress'&$orderby=CreatedDate: Returns summary data for all processes in Nintex Process Manager with the following conditions applied:

      • Filter by publish state 'InProgress'

      • Order by Created Date

  6. Click Send.

The return payload is displayed in JSON format.

Query the Reporting API