Krux API

Service Account Creation

A Service Account is required to consume the API and can be created using the following steps.

• Login to KruxMetrix using account with Administrator privileges.
• Navigate to Settings -> Users.
• Press Add User button which will open the New User page.
• On the New User page, check the Service Account checkbox and enter the required fields. Click Save to continue.

Authorization

This API utilizes Bearer Tokens for authorization. The Bearer Token must be passed in a key named “Authorization” in each subsequent call to the API.

AUTHORIZATION

Bearer Token

Token

<token>

Token Expiration

Tokens are valid for 7 days. Requests made using an expired token will result in 401 Unauthorized responses from the server and the Response Headers will contain the WWW-Authenticate key that has a value similar to Bearer error="invalid_token", error_description="The token expired at '10/07/2021 17:57:27'"

Application Program Interface (API)

Auth POST

https://metrixapi.kruxanalytics.com/users/auth

Used to authenticate user and obtain the Bearer Token from “token” in the json response. The token key returned in a successful authentication response is needed for all subsequent API calls.

BODY raw

{"Username":"service_account","Password":"service_account_password"} }

RESPONSE

{     "$id": "1",     "id": 12345,     "firstName": "Service",     "lastName": "Account",     "username": "service_account",     "password": null,     "token": "your_token",     "locked": false,     "companyID": 12345,     "configurationName": null,     "configurationID": 0,     "subscriptionList": "Krux Api",     "roleList": "API Service Account'" }

Errors
Errors occurring while authenticating will result in 401 Unauthorized.

{     "$id": "1",     "message": "Username or password is incorrect" }

Companies GET

https://metrixapi.kruxanalytics.com/api/v2/Export/Companies

Used to obtain CompanyIDs for all divisions in user’s organization for which the user has permission to export data. CompanyId is a required parameter for GetData call.

AUTHORIZATION

This request uses the Bearer Token

HEADERS

Authorization

Bearer <your_token>

RESPONSE

{ "Table": [    {      "CompanyID": 12345,      "CompanyName": "Demo Company",      "IsParentCompany": 0    } ] }

ExportTypes GET

https://metrixapi.kruxanalytics.com/api/v2/Export/ExportTypes

Used to obtain the list of unique queries available in the API that can be used to selectively return required data. “id” from the JSON response must be entered as the queryName parameter for the GetData call.

AUTHORIZATION

This request uses the Bearer Token

HEADERS

Authorization

Bearer <your_token>

RESPONSE

ID	DESCRIPTIO
DSRActivity	Returns all Daily Shift Report activities that have been added/deleted/modified since exportDateTime
DSRActivityEquipment	Returns all equipment attached to Daily Shift Report activities that have been added/deleted/modified since exportDateTime
DSREquipmentUsage	Returns all Daily Shift Report equipment that has been added/deleted/modified since exportDateTime
DSRConsumables	Returns all Daily Shift Report consumables that have been added/deleted/modified since exportDateTime
TSWorkersLabour	Returns all Timesheet workers that have been added/modified since exportDateTime
TSActivityLabour	Returns all workers attached to Timesheet activities that have been added/modified since exportDateTime
TSActivityEquipment	Returns all workers attached to Timesheet activities that have been added/deleted/modified since exportDateTime
EquipmentRental	Returns all Equipment Rentals that have been added/deleted/modified since exportDateTime
AdditionalCharges	Returns all Additional Charges added/deleted/modified since exportDateTime
DSR	Returns all Daily Shift Reports that have been added/deleted/modified since exportDateTime
TS	Returns all Timesheets that have been added/deleted/modified since exportDateTime
DSRFluids	Returns all Daily Shift Report fluids that have been added/deleted/modified since exportDateTime
Holes	Returns all Holes that have been added/deleted/modified since exportDateTime
DSRSamples	Returns all Daily Shift Report samples that have been added/deleted/modified since exportDateTime
DSRWorkersLabour	Returns all Daily Shift Report workers labour that have been added/deleted/modified since exportDateTime
DSRActivityLabour	Returns all Daily Shift Report activity labour that have been added/modified since exportDateTime
DSRPerDrillRate	Returns all DSR Per Drill Rate that have been added/ modified since exportDateTime
DSRAdditionalCharges	Returns all Additional Charges added/deleted/modified in the DSRs since exportDateTime
TSConsumables	Returns all Timesheet consumables that have been added/ modified since exportDateTime
TSFluids	Returns all Timesheet Fluids that have been added/ modified since exportDateTime
DSRActivityCodes	Returns all Krux unique codes for the DSR Activities that have been added / deleted / modified. The codes include unique Krux level Work SubCategoryID, SubCategoryTypeID, ContractActivityID ContractActivityRateID codes for DSR Activities.
DSRCoreRuns	Returns all Daily Shift Report Core Runs that have been added/deleted/modified since exportDateTime
DSRDirectionalRuns	Returns all Daily Shift Report Directional Runs that have been added/deleted/modified since exportDateTime

 

GetData GET

https://metrixapi.kruxanalytics.com/api/v2/Export/GetData/?companyId=12345&exportDateTime=2021-01-22 17:42:08.390&queryName=TS

Used to export data based on queryName specified in the call. All available options can be retrieved using the ExportTypes call.

 AUTHORIZATION

This request uses the Bearer Token

HEADERS

Authorization

Bearer <your_token>

REQUEST PARAMETERS

Key	Value	Description
companyId	Integer (12345)	The company identifier used to specify which division of the company data will be returned for. The CompanyID for all divisions in your organization can be obtained by making a request to https://metrixapi.kruxanalytics.com/api/v2/Export/Companies
exportDateTime	Date (2021-01-22 17:42:08.390)	The starting datetime after which data is exported. Any data that has been added, deleted or modified since exportDateTime will be returned.
queryName	String (DSR)	The list of all queries can be obtained by making a request to https://metrixapi.kruxanalytics.com/api/v2/Export/ExportTypes

Errors
Invalid parameters will result in a 400 Bad Requests status. The message keyname in the response json will contain the parameter name with the validation error. The 3 possible messages include:

• Invalid queryName
• Invalid companyId
• Invalid exportDateTime

{     "$id": "1",     "message": "Invalid queryName" }

RESPONSE

Each queryName has a unique json response.

Working with the API Data

UIDs

Every data record returned by the API has a unique identifier (UID). Each UID starts with an integer that identifies what type of data it is and then includes one to three additional IDs required to ensure uniqueness of the UID. The general format is of the UID is

Data Type – Report Record ID – Charge ID – Context Dependent ID

Data Type – An integer that identifies what type of data the record is. Included in all UIDs.

Report Record ID – Unique identifier for the report record enter by the user (e.g. A drilling activity record from a Daily Shift Report). Included in all UIDs.

Charge ID – Unique identifier for the charges calculated based on an applicable rate in the contract. (e.g. Charges calculated based on a meterage rate for a drilling activity). Only included for data that can have associated contract rates.

Context Dependent ID – Will be different for each type of data. Only included when required for uniqueness.

The format for each individual UID is included in the following sections.

Processing Incremental Data

All data returned by the GetData method is incremental data based on the exportDateTime parameter provided. This means that only data that is new or has changed in some way since the provided exportDateTime will be included. If any of the following have occurred since exportDateTime the record will be included:

• • DSR/TS
    • Approved for contracts with Report Approval Required = Yes
    • Validated for contracts with Report Approval Required = No
    • Rejected
    • Deleted
    • Header data was modified
    • Individual record within the report was added, modified, or deleted
    • Applicable contract rate was added, modified, or deleted
  • Additional Charge/Equipment Rental is approved, modified, or deleted
  • Hole Records was added, modified, or deleted

Records with DeletedFlag = 'N' represent approved data non-deleted data.

On the other hand, DeletedFlag = 'Y' can indicate one of the following scenarios:

1. New Data: Data that is not yet approved and is currently pending approval.
2. Rejected Data: Data that was rejected by an approver and has reverted to a pending status.
3. Deleted Data: Records removed from various sources, such as the Daily Shift Report or Timesheet and rate records deleted from contracts (which will in turn delete associated charges on DSR, TS, etc.). So, in order to distinguish actual deleted data from new or rejected data, we introduced the DataDeleted flag.

To process the new incremental data against existing dataset, use the following logic:

UID Exist in Dataset	Delete Flag	DataDeleted	Action Required
Y	Y	Y	Remove record from dataset
Y	Y	N	Remove record in dataset
Y	N	N	Update record in dataset
N	Y	Y	Disregard, do not add record to dataset
N	Y	N	Disregard, do not add record to dataset
N	N	N	Add record to dataset

Using Report and Charge Data

Each type of data returned by the API consists of just report data or report and charge data from an associated contract rate. If a data type also includes charge data, its UID will include a charge ID. The only exception to this is Additional Charges, as they are charge records in and of themselves; they have no associated contract rates. In general, the fields that are associated with the charge portion of a records are:

• • Billing Type
  • Total Charges
  • Currency Code

The other data fields are associated with the report portion of the record.

Each individual report record can have multiple associated contract rates. This means that one report record can return multiple unique records in the API with different charges.

Example - A DSR drilling activity with a meterage rate and an hourly rate. This will return 2 records in the API.

Data Field	Record 1	Record 2
UID	1-12345-333	1-12345-777
DailyReportID	16556	16556
HoleID	47478	47478
Hole	TYC-1209	TYC-1210
Activity	Drilling	Drilling
Type	Coring	Coring
Bit Size	NQ	NQ
DistanceDrilledFrom	53	53
DistanceDrilledTo	75	75
Billable	Yes	Yes
ActivityHours	4	4
TotalManHours	8	8
Penetration	22	22
BillingType	Per Distance	Per Activity Hour
DistanceFromToUnitAbbr	m	m
TotalCharges	1430	200
CurrencyCode	CAD	CAD

Depending how you want to manipulate the API data you may have to breakout the UID in its separate IDs.

Example Calculation 1 - If you want to find the total of all charges for report record, you have to sum the TotalCharges field for all records that have the same Report Record ID.

Example Calculation 2 – If you want to find total activity hours for a Daily Shift Report. You first have to group the activity records so that you have only one record per Report Record ID. Then sum the Activity Hours field for all activities with the same DailyReportID.

Hole Data

Hole UID Format

14-[HoleID]

The HoleID column is the unique identifying number for a hole. Any record associated directly with a hole will include HoleID as well as Hole. Hole is the name for that hole entered by the user and displayed to identify the hole for the users in the KruxMetrix and KruxLog. Hole is very often unique but it is not guaranteed to be unique; for the purposes of processing the data from the API, HoleID must be used.

Daily Shift Report (DSR) Data

DSR Data Definitions:
DSR UID Format

11-[DailyReportID]

The DailyReportID column is the unique identifying number for the Daily Shift Report (DSR). All associated data for the same DSR will have the same DailyReportID.

DSRWorkerLabour UID Format

16-[DSRWorkerLabourID]-[ DSRWorkerLabourChargeID]

The DSRWorkerLabourID is the unique identifier for the workers with payroll hours entered in the DSR. The DSRWorkerLabourChargeID is the unique identifier for the charges calculated for that worker based on an applicable rate in the contract. If there is no applicable rate in the contract, DSRWorkerLabourChargeID will be null.

DSRActivity UID Format

1-[DSRActivityID]-[DSRActivityChargeID]

The DSRActivityID is the unique identifier for the activity entered in the DSR. The DSRActivityChargeID is the unique identifier for the charges calculated for that activity based on an applicable rate in the contract. If there is no applicable rate in the contract, DSRActivityChargeID will be null.

DSRActivityEquipment UID Format

3-[DSRActivityEquipmentID]-[DSRActivityEquipmentChargeID]

The DSRActivityEquipmentID is the unique identifier for the equipment entered for an activity in the DSR. The DSRActivityEquipmentChargeID is the unique identifier for the charges calculated for that equipment based on an applicable rate in the contract. If there is no applicable rate in the contract, DSRActivityEquipmentChargeID will be null.

DSRActivityLabour UID Format

17-[DSRActivityLabourID]-[ DSRActivityLabourChargeID]

The DSRActivityLabourID is the unique identifier for the workers with man hours entered for an activity in the DSR. The DSRActivityLabourChargeID is the unique identifier for the charges calculated for that worker based on an applicable rate in the contract. If there is no applicable rate in the contract, DSRActivityLabourChargeID will be null.

DSREquipmentUsage UID Format

4-[DSREquipmentID]-[DSREquipmentChargeID] ]-[EquipmentUnitID]

The DSREquipmentID is the unique identifier for the equipment record entered in the DSR. The EquipmentUnitID is the unique identifier for a specific equipment unit that was included in the equipment record. If no specific equipment unit is selected, EquipmentUnitID will be null. The DSREquipmentChargeID is the unique identifier for the charges calculated for that equipment based on an applicable rate in the contract. If there is no applicable rate in the contract, DSREquipmentChargeID will be null.

DSRConsumables UID Format

5-[DSRConsumablesID]-[DSRConsumablesChargeID]

The DSRConsumablesID is the unique identifier for the consumable entered in the DSR. The DSRConsumablesChargeID is the unique identifier for the charges calculated for that consumable based on an applicable rate in the contract. If there is no applicable rate in the contract, DSRConsumablesChargeID will be null.

DSRFluids UID Format

13-[DSRFluidsID]-[DSRFluidsChargeID]

The DSRFluidsID is the unique identifier for the fluid volume entered in the DSR. The DSRFluidsChargeID is the unique identifier for the charges calculated for that fluid based on an applicable rate in the contract. If there is no applicable rate in the contract, DSRFluidsChargeID will be null.

DSRSamples UID Format

15-[DSRSamplesID]

The DSRSamplesID is the unique identifier for the sample entered in the DSR.

DSRPerDrillRate UID Format

18-[DSRPerDrillRateID]

The DSRPerDrillRateID is the unique identifier for the Per Drill Rate entered in the DSR.

DSRAdditionalCharges UID Format

10-[DSRAdditionalChargeID]

The DSRAdditionalChargeID is the unique identifier for the DSR additional charge record.

DSRActivityCodes UID Format

22-[DSRActivityID]-[DSRActivityChargeID]

The DSRActivityID is the unique identifier for the activity entered in the DSR. The DSRActivityChargeID is the unique identifier for the charges calculated for that activity based on an applicable rate in the contract. If there is no applicable rate in the contract, DSRActivityChargeID will be null. 

DSRCoreRun UID Format

23-[DailyReportHoleActivityCoreRunID]

The DailyReportHoleActivityCoreRunID is the unique identifier for the core run entered for a drilling activity in the DSR.

DSRDirectionalRun UID Format

23-[ DailyReportHoleActivityDirectionalRunID]

The DailyReportHoleActivityCoreRunID is the unique identifier for the core run entered for a drilling activity in the DSR.

Timesheet (TS) Data

TS UID Format

12-[TimesheetID]

The TimesheetID column is the unique identifying number for the Timesheet (TS). All associated data for the same timesheet will have the same TimesheetID.

TSWorkersLabour UID Format

6-[TSWorkerLabourID]-[ TSWorkerLabourChargeID]

The TSWorkerLabourID is the unique identifier for the workers with payroll hours entered in the TS. The TSWorkerLabourChargeID is the unique identifier for the charges calculated for that worker based on an applicable rate in the contract. If there is no applicable rate in the contract, TSWorkerLabourChargeID will be null.

TSActivityLabour UID Format

7-[TSActivityLabourID]-[TSActivityLabourChargeID]

The TSActivityLabourID is the unique identifier for the workers with man hours entered for an activity in the TS. The TSActivityLabourChargeID is the unique identifier for the charges calculated for that worker based on an applicable rate in the contract. If there is no applicable rate in the contract, TSActivityLabourChargeID will be null.

TSActivityEquipment UID Format

8-[TSActivityEquipmentID]-[TSActivityEquipmentChargeID]

The TSActivityEquipmentID is the unique identifier for the equipment entered for an activity in the TS. The TSActivityEquipmentChargeID is the unique identifier for the charges calculated for that equipment based on an applicable rate in the contract. If there is no applicable rate in the contract, TSActivityEquipmentChargeID will be null.

TSConsumables UID Format

20-[TSConsumablesID]

The TSAConsumablesID is the unique identifier for the timesheet consumables entered for an activity in the TS.

TSFluid UID Format

19-[TSFluid]

The TimesheetFluidConsumptionID is the unique identifier for the timesheet fluid consumables entered for an activity in the TS.

Equipment Rentals Data

EquipmentRental UID Format

9-[EquipmentRentalID]-[EquipmentRentalChargeID]

The EquipmentRentalID is the unique identifier for the equipment rental record. The EquipmentRentalChargeID is the unique identifier for the charges calculated for that equipment rental based on an applicable rate in the contract. If there is no applicable rate in the contract, EquipmentRentalChargeID will be null.

Additional Charges Data

AdditionalCharges UID Format

10-[AdditionalChargeID]

The AdditionalChargeID is the unique identifier for the additional charge record.

 

 

 

 

 

 

 

 

Timesheet (TS) Data – (Additional Tables)

TS UID Format

12-[TimesheetID]

The TimesheetID column is the unique identifying number for the Timesheet (TS). All associated data for the same timesheet will have the same TimesheetID.

TSWorkersLabour UID Format

6-[TSWorkerLabourID]-[ TSWorkerLabourChargeID]

The TSWorkerLabourID is the unique identifier for the workers with payroll hours entered in the TS. The TSWorkerLabourChargeID is the unique identifier for the charges calculated for that worker based on an applicable rate in the contract. If there is no applicable rate in the contract, TSWorkerLabourChargeID will be null.

TSActivityLabour UID Format

7-[TSActivityLabourID]-[TSActivityLabourChargeID]

The TSActivityLabourID is the unique identifier for the workers with man hours entered for an activity in the TS. The TSActivityLabourChargeID is the unique identifier for the charges calculated for that worker based on an applicable rate in the contract. If there is no applicable rate in the contract, TSActivityLabourChargeID will be null.

TSActivityEquipment UID Format

8-[TSActivityEquipmentID]-[TSActivityEquipmentChargeID]

The TSActivityEquipmentID is the unique identifier for the equipment entered for an activity in the TS. The TSActivityEquipmentChargeID is the unique identifier for the charges calculated for that equipment based on an applicable rate in the contract. If there is no applicable rate in the contract, TSActivityEquipmentChargeID will be null.

TSConsumables UID Format

20-[TSConsumablesID]-[TSConsumablesChargeID]

The TSConsumablesID is the unique identifier for the consumables in the TS. The TSConsumablesChargeID is the unique identifier for the charges calculated for that consumable based on an applicable rate in the contract. If there is no applicable rate in the contract, TSConsumablesChargeID will be null.

 

TSFluids UID Format

19-[TSFluidsID]-[ TSFluidsChargeID]

The TSFluidsID is the unique identifier for the fluids entered in the TS. The TSFluidsChargeID is the unique identifier for the charges calculated for that fluid based on an applicable rate in the contract. If there is no applicable rate in the contract, TSFluidsChargeID will be null.

Equipment Rentals Data

EquipmentRental UID Format

9-[EquipmentRentalID]-[EquipmentRentalChargeID]

The EquipmentRentalID is the unique identifier for the equipment rental record. The EquipmentRentalChargeID is the unique identifier for the charges calculated for that equipment rental based on an applicable rate in the contract. If there is no applicable rate in the contract, EquipmentRentalChargeID will be null.

Additional Charges Data

AdditionalCharges UID Format

10-[AdditionalChargeID]

The AdditionalChargeID is the unique identifier for the additional charge record.