Overview

This is a REST API that provides access to Riskcast data.

Usage

An API key is required in order to gain access. This will be used to generate a token that provides both authorization and authentication. The API key is a 40 character alphanumeric string value specific to your Riskcast tenant account. The API key is associated to an integration account specific to your Riskcast account that will have access to all of your Riskcast resources. Therefore, it is important that you safeguard your API key and it not be shared with anyone. A new API key can be generated if the original is compromised. Integration into this API using user-specific credentials is currently NOT supported.

The API key should be added as an x-api-key header in all HTTPS requests. HTTP (non SSL) requests are not supported. If your API key is a read only key, then only GET requests will be allowed. All other requests will be denied and return a 403 Forbidden error.

Any date fields labeled as Integer should be formatted as YYYYMMDD. This applies to both query parameters and entity fields. For example, February 9th, 2023 would be formatted as 20230209.

In contrast, the updatedAfter date available as a parameter in most endpoints must be provided in ISO 8601 format. For example, February 9th, 2023 in UTC would be formatted as 2023-02-09T00:00:00Z.

Several endpoints support paging. However, the page parameter is optional. If it is NOT provided, then all available records are returned, as long as the count is equal to or less than 8000 records. An error will be thrown if there are more than 8000 records and a page is not provided.

Riskcast provides production and test environments. If a test environment has not been created for your Riskcast account, you will need to submit a request to customer support to have one created for you. Both the production and test environments provide access to this API. The URL endpoints for each environment are listed below.

API Rate Limits, Quotas, and Throttling

To ensure fair usage and maintain system stability, the following API rate limits apply:

• Rate Limits: Requests are throttled to a maximum of 5,000 requests per hour per API key. If you exceed this limit, the API fails the limit-exceeding requests and returns a 429 Too Many Requests error.
• Retry Handling: Clients should implement exponential backoff strategies when handling 429 errors. Suggested retry intervals are:
  • First retry: Wait 1 second
  • Second retry: Wait 2 seconds
  • Third retry: Wait 4 seconds, etc.
• Burst Limit: A short-term burst allowance of up to 50 requests per second is permitted for a maximum of 5 seconds, after which normal rate limits apply.
• Data Quota: The maximum data payload allowed per API request is 5MB. Requests exceeding this limit will receive a 413 Payload Too Large error.

Some of the list end points have a record limit associated to them. If the record limit exceeds our internal limits, an error 413 Maximum results count allowed is #### will be returned. Upon getting this error, the client should adjust the parameters to lower the number of records retrieved.

Filtering

It is possible to filter records returned from list endpoints that accept the filter query parameter. The syntax for filter query is very similar to the one specified in OData Standard. The only operators supported at the moment are: and, eq. For example, the following query would return the list of projects that are closed: GET /projects&filter=closed eq true. When constructing these queries, it's important to follow the rules below:

• Only fields present on the 'read' schema of the specified resource can be used for filtering
• Operators and operands must be separated by a single space character (left_operand operator right_operand)
• String values must be quoted via single quotes (field eq 'string value')
• Number and boolean values shouldn't be quoted (field eq 10, field eq false)
• Filters can be combined only using and operator, within the same filter query parameter (filter=field1 eq 'value1' and field2 eq true)
• A known limitation prevents search if the field being searched includes one of the following special characters: %, +, /, ?, #, &, '

Payroll Export Workflow

What follows is an overview of the endpoints and the workflows needed to process payroll exports.

STEP 1

Get Export Formats for the company. An export format defines the schema that the data will be retrieved in. Riskcast allows a company to have more than one export format. However, most clients only end up using one format, per company. Each company will require a unique export format Id, even if every company ends up using the same schema. Use this endpoint to get the id for the Export Format you desire.

GET /core/payrollexports/exportformats?companyId={{companyId}}

STEP 2

Once you know the export format Id for the company, get a list of payroll exports for the given week end date and projectIds. If projectIds is an empty array, then all projects for that week are retrieved. Provide the flag isReceivedByERP as true/false to specify whether you want exports that have already been received and processed. Send isReceivedByERP = false to retrieve payroll exports that have not yet been received and processed. If isReceivedByERP is not provided, then all payroll exports are sent back.

GET /core/payrollexports?exportFormatId={{exportFormatId}}&weekEndDateKey={{weekEndDateKey}}&isReceivedByERP={{isReceivedByERP}}&projectId={{projectId1}}&projectId={{projectId2}}

STEP 3

For each available payroll export Id, request the export data for that export. This contains the formatted labor, equipment, and "other" export data using the schema specified by the export format Id. The type parameter is optional and can be one of the following values: labor, equipment, other. If type is not provided, then labor is returned. The snapshot parameter is optional and can be one of the following values: true, false. If snapshot is true, then the data is returned as a snapshot of the data at the time of the export. If snapshot is false or not provided, then the data is returned as a live view of the data.

GET /core/payrollexports/{{id}}/data?type={{type}}&snapshot={{snapshot}}

STEP 4

Optional. Update the status of the payroll export to set the status of isReceivedByERP to true. It is recommended that this is done so that future requests in STEP 2 only retrieve exports that have NOT yet been processed.

PUT /core/payrollexports/{{id}}/received

STEP 5

In order to reset a payroll export if an error occurs, use the following end point

PUT /core/payrollexports/{{id}}/reset