BitCurb reporting uses Open Data Protocol (OData) to expose resources representing historical data throughout a single REST endpoint address https://api.bitcurb.com/.

  • The exposed entities are not related and multiple entities cannot be included inline in the response of you requests.
  • This endpoint is only accessible if the consumer is authenticated with valid BitCurb account.
  • The results sets cannot be joined at request and could be only consumed separately.

We provide report endpoints for the Crunch and ETL operations.

Crunch Operations

Below is a diagram of the relationship between entities available for REST consumption.

CrunchRuns

[Get] https://api.bitcurb.com/api/1.0/reports/CrunchRuns

Provides historical information about the execution of every rule. Both filter and matching rules are tracked and statistical information about their executions is stored.

Field Description can be blank
id unique identifier of the entity row No
tenantID unique identifier of your account No
crunchTemplateName The name of the template containing one or more rules for execution Yes
ruleBody definition of the rule that is executed No
varianceExpression definition of the variance expression used for rule’s execution. It is applicable to matching rules only. Filtering rules don’t have variance defined Yes
consumerType the type of the consumer that invoked the rules’ execution.

possible values are:

  • 1-API
  • 2-Excel App
No
leftCount the count of the rows passed for processing from the first side – $1 No
rightCount the count of the rows passed for processing from the first side – $2 No
totalCount the total number of rows processed No
createdBy username of the user account, who triggered the rule’s execution No
createdTimeUTC datetime in UTC when the record is created No
[
   {
      "id":11474,
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a",
      "crunchTemplateName":"Code Samples - Crunch API",
      "ruleBody":"$1.AccountIdentification == $2.AccountIdentification \nAND $1.TransactionValueDate == $2.TransactionValueDate \nAND $1.TransactionType == $2.TransactionType \nAND $1.AccountServingInstitution == $2.AccountServingInstitution",
      "varianceExpression":"Less 20.0000",
      "consumerType":"1",    
      "leftCount":3,
      "rightCount":5,
      "totalCount":8,
      "createdBy":"support@bitcurb.com",
      "createdTimeUtc":"2020-07-07T11:10:09.537"
   },
   {
      "id":11473,
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a",
      "crunchTemplateName":"Code Samples - Crunch API",
      "ruleBody":"$2.AccountServingInstitution == $1.AccountServingInstitution AND $2.Amount == $1.Amount",
      "varianceExpression":null,
      "consumerType":"1",
      "leftCount":2,
      "rightCount":3,
      "totalCount":5,
      "createdBy":"support@bitcurb.com",
      "createdTimeUtc":"2020-07-07T11:10:09.45"
   },
   {
      "id":11472,
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a",
      "crunchTemplateName":"Code Samples - Crunch API",
      "ruleBody":"$1.AccountIdentification == $2.AccountIdentification \nAND $1.TransactionValueDate == $2.TransactionValueDate \nAND $1.TransactionType == $2.TransactionType \nAND FIND($2.AccountServingInstitution, $1.AccountServingInstitution) >= 1",
      "varianceExpression":null,
      "consumerType":"1",
      "leftCount":4,
      "rightCount":7,
      "totalCount":11,
      "createdBy":"support@bitcurb.com",
      "createdTimeUtc":"2020-07-07T11:10:09.437"
   },
   {
      "id":11471,
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a",
      "crunchTemplateName":null,
      "ruleBody":"$1.AccountIdentification == $2.AccountIdentification AND $1.TransactionValueDate == $2.TransactionValueDate AND \r\n                $1.TransactionType == $2.TransactionType AND $1.AccountServingInstitution == $2.AccountServingInstitution",
      "varianceExpression":"Less 20.0",
      "consumerType":"1",
      "leftCount":4,
      "rightCount":7,
      "totalCount":11,
      "createdBy":"support@bitcurb.com",
      "createdTimeUtc":"2020-07-07T11:09:45.063"
   },
   {
      "id":11470,
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a",
      "crunchTemplateName":null,
      "ruleBody":"$1.AccountServingInstitution == $2.AccountServingInstitution AND $1.Amount == $2.Amount",
      "varianceExpression":null,
      "consumerType":"1",
      "leftCount":4,
      "rightCount":7,
      "totalCount":11,
      "createdBy":"support@bitcurb.com",
      "createdTimeUtc":"2020-07-07T11:09:37.647"
   },
   {
      "id":10204,
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a",
      "crunchTemplateName":"Code Samples - Filters API",
      "ruleBody":"$1.status != \"Discontinued\" AND ISBLANK($1.internal_memory_mb) == FALSE AND ISBLANK($1.primary_camera_mp) == FALSE AND TONUMBER($1.internal_memory_mb) >= 8192 AND \r\nTONUMBER($1.primary_camera_mp) >= 8",
      "varianceExpression":null,
      "consumerType":"1",
      "leftCount":3,
      "rightCount":0,
      "totalCount":3,
      "createdBy":"support@bitcurb.com",
      "createdTimeUtc":"2020-06-23T07:34:32.24"
   }
]

 

CrunchRunDetails

[Get] https://api.bitcurb.com/api/1.0/reports/CrunchRunsDetails

Provides historical data about how each executed rule performed and what is the result of its execution.

Both filter and matching rules are tracked, and statistical information about their executions is stored.

When matching rule is executed, two records are created in CrunnchRunDetails. The first one represent the filtering part of the crunch process, and the second one will hold the statistics about what has been matched.

 

Field Description can be blank
id unique identifier of the entity row No
tenantID unique identifier of your account No
crunchHistoryID reference to the CrunchRuns entity No
isFilter indicator if the rule is Filtering or Matching rule

possible values:

  • true – Filtering Rule
  • false – Matching Rule
No
leftCount The count of the rows from the left side $1 after rule is executed. If filtering rule – then it contains the number of filtered items from the left site (i.e. result number). If crunch rule – then it contains the number of the items from the left side that are in a result group No
rightCount The count of the rows from the right side $2 after rule is executed. If filtering rule – then it contains the number of filtered items from the right site (i.e. result number). If crunch rule – then it contains the number of the items from the right side that are in a result group No
groupCount The number of groups created as result of the rule’s execution. This is only available for Crunch rules Yes
varianceCount The total number of variance items created as result of the rule’s execution. It represents the number of variances in all result groups. This is only available for Crunch rules Yes
timeInMilliseconds the time that rule’s execution took to complete No
isSuccessful indicator if the rule is successfully executed

possible values:

  • true – successfully executed rule
  • false – execution completed with error
No
createdTimeUTC datetime in UTC when the record is created No
correlationID guid identifier holding reference to logged error. you can reach out BitCurb support providing this identifier to get details about the error No
[
   {
      "id":11612,
      "crunchHistoryID":11474,
      "isFilter":false,
      "leftCount":1,
      "rightCount":2,
      "groupCount":1,
      "varianceCount":1,
      "timeInMilliseconds":1,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:10:09.537",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11611,
      "crunchHistoryID":11474,
      "isFilter":true,
      "leftCount":1,
      "rightCount":2,
      "groupCount":null,
      "varianceCount":null,
      "timeInMilliseconds":1,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:10:09.537",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11610,
      "crunchHistoryID":11473,
      "isFilter":false,
      "leftCount":2,
      "rightCount":2,
      "groupCount":2,
      "varianceCount":0,
      "timeInMilliseconds":1,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:10:09.45",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11609,
      "crunchHistoryID":11473,
      "isFilter":true,
      "leftCount":2,
      "rightCount":2,
      "groupCount":null,
      "varianceCount":null,
      "timeInMilliseconds":1,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:10:09.45",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11608,
      "crunchHistoryID":11472,
      "isFilter":false,
      "leftCount":1,
      "rightCount":2,
      "groupCount":1,
      "varianceCount":0,
      "timeInMilliseconds":11,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:10:09.437",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11607,
      "crunchHistoryID":11472,
      "isFilter":true,
      "leftCount":2,
      "rightCount":4,
      "groupCount":null,
      "varianceCount":null,
      "timeInMilliseconds":18,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:10:09.437",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11606,
      "crunchHistoryID":11471,
      "isFilter":false,
      "leftCount":1,
      "rightCount":2,
      "groupCount":1,
      "varianceCount":1,
      "timeInMilliseconds":17,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:09:45.063",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11605,
      "crunchHistoryID":11471,
      "isFilter":true,
      "leftCount":1,
      "rightCount":2,
      "groupCount":null,
      "varianceCount":null,
      "timeInMilliseconds":3,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:09:45.063",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11604,
      "crunchHistoryID":11470,
      "isFilter":false,
      "leftCount":3,
      "rightCount":3,
      "groupCount":3,
      "varianceCount":0,
      "timeInMilliseconds":31,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:09:37.647",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":11603,
      "crunchHistoryID":11470,
      "isFilter":true,
      "leftCount":3,
      "rightCount":3,
      "groupCount":null,
      "varianceCount":null,
      "timeInMilliseconds":94,
      "isSuccessful":true,
      "createdTimeUtc":"2020-07-07T11:09:37.647",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":10300,
      "crunchHistoryID":10204,
      "isFilter":true,
      "leftCount":2,
      "rightCount":0,
      "groupCount":null,
      "varianceCount":null,
      "timeInMilliseconds":12,
      "isSuccessful":true,
      "createdTimeUtc":"2020-06-23T07:34:32.24",
      "correlationID":"00000000-0000-0000-0000-000000000000",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   }
]

 

CrunchRunsGroups

[Get] https://api.bitcurb.com/api/1.0/reports/CrunchRunsGroups

Provides historical data about each group created as a result of executing matching rule.

Only matching rules are tracked and statistical information about their executions is stored.

Field Description Can be blank
id unique identifier of the entity row No
tenantID unique identifier of your account No
crunchHistoryID reference to the CrunchRuns entity No
groupIdentifier guid identifier that is returned to the consumer after the rule has been processed successfully. No
varianceValue the value for the variance item created for the current group record No
groupElementIDs Concatenated list of all id that belong to the group. they are the same as those that are passed as input when rule is invoked No

If you have a crunch operation that returned the following result:

{
   "groups":[
      {
         "identifier":"2b99d4b7-0f5d-4a90-9d6b-e29368118ddf",
         "elements":[
            4,
            3,
            9
         ],
         "variance":16.89
      }
   ]
}

Then the same “identifier” value will be presented after that in the result of CrunchRunGroups relating your executed Crunch operation to the stored statistical information.

[
   {
      "id":153,
      "crunchHistoryID":11474,
      "groupIdentifier":"e88999f6-ac9b-42c6-b8b4-07cbba41765a",
      "varianceValue":16.8900,
      "groupElementIDs":"4,3,9",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":152,
      "crunchHistoryID":11473,
      "groupIdentifier":"ccc1b779-f0cc-4944-96c7-2c98eec7c3f9",
      "varianceValue":0.0,
      "groupElementIDs":"10,6",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":151,
      "crunchHistoryID":11473,
      "groupIdentifier":"b96df8d3-d94e-4ce4-a5b2-a79306079ec2",
      "varianceValue":0.0,
      "groupElementIDs":"11,7",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":150,
      "crunchHistoryID":11472,
      "groupIdentifier":"055fdf33-1cc0-4b7a-b647-3e6f51501362",
      "varianceValue":0.0,
      "groupElementIDs":"1,2,8",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":149,
      "crunchHistoryID":11471,
      "groupIdentifier":"2b99d4b7-0f5d-4a90-9d6b-e29368118ddf",
      "varianceValue":16.8900,
      "groupElementIDs":"4,3,9",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":148,
      "crunchHistoryID":11470,
      "groupIdentifier":"a5178103-4f34-4ac3-8839-586e0781128a",
      "varianceValue":0.0,
      "groupElementIDs":"11,7",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":147,
      "crunchHistoryID":11470,
      "groupIdentifier":"90c221c1-ed22-4f58-9c79-78d14579ae52",
      "varianceValue":0.0,
      "groupElementIDs":"10,6",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   },
   {
      "id":146,
      "crunchHistoryID":11470,
      "groupIdentifier":"baaa2554-da59-4f8f-bcf1-9e105095782b",
      "varianceValue":0.0,
      "groupElementIDs":"9,3",
      "tenantID":"ed1c88e8-97cf-4e6d-89aa-d3ab46247a3a"
   }
]

 

CrunchRunGroups – Filtering Rule – response will be always empty []

ETL Operations

Below is a diagram of the relationship between entities available for REST consumption.
All operations are GET consumed and you must provide a valid authentication token (access token), when consuming any of the endpoints.

ETLHistory

This operation returns a list of all executed ETL operations.
[Get] https://api.bitcurb.com/api/1.0/reports/ETLHistory

Field Description Can be blank
Id unique identifier of the entity row No
userID Identifier of the user who executed the operation No
clientType The consumer that executed the operation
Api = 1,
Excel = 2
No
etlTemplateID etlTemplateID Unique identifier of the ETL template defined in BitCurb portal
Empty if the ETL operation is executed through API and no templateId has been referred in the payload
Yes
dataContainerType Identifies the data container that stores your files
Dropbox = 1,
SFTP = 2,
OneDrive = 3
No
sourceType Type of the file that has been processed
Swift940 = 1,
Swift950 = 2,
CSV = 3
No
sourceFilePath String representing the file path to your processed file.
Empty if the ETL operation is executed through API and no templateId has been referred in the payload
Yes
recordCount The number of messages in the file. If the file is SWIFT type the number of records represent the number of SWIFT messages and it could be different than the lineCount No
lineCount The number of rows (transactions) processed in the file No
containerTimeInMilliseconds The time consumed for reading ETL files from the data container.Empty if the ETL operation is executed through API and no templateId has been referred in the payload Yes
parseTimeInMilliseconds The time consumed by BitCurb ETL Engine to read the ETL file to be processed No
transformationTimeInMilliseconds The time consumed by BitCurb ETL Engine to apply formulas if any or the mapping fields No
totalTimeInMilliseconds The total time for completing the ETL operation No
correlationID guid identifier holding reference to a logged error. you can reach out BitCurb support providing this identifier to get details about the error Yes
createdTimeUtc datetime in UTC when the record is created No
[
   {
      "id":73,
      "userID":1111,
      "clientType":1,
      "etlTemplateID":10,
      "dataContainerType":2,
      "sourceType":2,
      "sourceFilePath":"/bitcurb/bitcurb/swift950/input/MT950_blocks12345_C27Warning.txt",
      "recordCount":3,
      "lineCount":10,
      "containerTimeInMilliseconds":350,
      "parseTimeInMilliseconds":11,
      "transformationTimeInMilliseconds":361,
      "totalTimeInMilliseconds":574,
      "correlationID":null,
      "createdTimeUtc":"2020-07-03T11:45:29.25"
   },
   {
      "id":72,
      "userID":1111,
      "clientType":1,
      "etlTemplateID":null,
      "dataContainerType":null,
      "sourceType":3,
      "sourceFilePath":null,
      "recordCount":10,
      "lineCount":10,
      "containerTimeInMilliseconds":null,
      "parseTimeInMilliseconds":1059,
      "transformationTimeInMilliseconds":14,
      "totalTimeInMilliseconds":1169,
      "correlationID":null,
      "createdTimeUtc":"2020-07-03T11:05:54.88"
   },
   {
      "id":64,
      "userID":1111,
      "clientType":1,
      "etlTemplateID":4,
      "dataContainerType":2,
      "sourceType":1,
      "sourceFilePath":"/bitcurb/bitcurb/swift/input/MT940_blocks4.txt",
      "recordCount":2,
      "lineCount":4,
      "containerTimeInMilliseconds":589,
      "parseTimeInMilliseconds":8,
      "transformationTimeInMilliseconds":600,
      "totalTimeInMilliseconds":805,
      "correlationID":null,
      "createdTimeUtc":"2020-06-23T07:43:52.863"
   }
]

ETLErrors

This operation returns the errors logged during the execution of an ETL operation. If no errors are logged, the execution returns empty json array [].
A valid “id” from ETLHistory result must be provided as value for etlHistoryID parameter.
[Get] https://api.bitcurb.com/api/1.0/reports/ETLErrors?etlHistoryID=<ETLHistoryID>

Field Description Can be blank
etlHistoryID Id of ETLHistory table identifying an ETL operation that has been executed No
errorType Identifies the type of the error that has been logged
Parser = 1 – error at parser level
Message = 2 – error at message level. Applicable to SWIFT files
Field = 3 – error at the field level. Applicable to SWIFT files
Transformation = 4 – Formula error
No
label String identifying the source of the error
Contains the SWIFT field name or CSV column if the error is coming from a particular field
No
message Error message No
lineNumber Line number from the ETL file that is the source of the error Yes
cellNumber Column number of the ETL file that is the source of the error Yes
expression Formula expression that is the source of the error Yes

For example: https://api.bitcurb.com/api/1.0/reports/ETLErrors?etlHistoryID=64

[
   {
      "etlHistoryID":64,
      "errorType":2,
      "label":"Message #1",
      "message":"{1: Basic Header Block} is not presented in your swift content.",
      "lineNumber":null,
      "cellNumber":null,
      "expression":null
   },
   {
      "etlHistoryID":64,
      "errorType":2,
      "label":"Message #1",
      "message":"{2: Application Header Block} is not presented in your swift content.",
      "lineNumber":null,
      "cellNumber":null,
      "expression":null
   },
   {
      "etlHistoryID":64,
      "errorType":2,
      "label":"Message #1",
      "message":"{3: User header block} is not presented in your swift content.",
      "lineNumber":null,
      "cellNumber":null,
      "expression":null
   },
   {
      "etlHistoryID":64,
      "errorType":2,
      "label":"Message #2",
      "message":"{1: Basic Header Block} is not presented in your swift content.",
      "lineNumber":null,
      "cellNumber":null,
      "expression":null
   },
   {
      "etlHistoryID":64,
      "errorType":2,
      "label":"Message #2",
      "message":"{2: Application Header Block} is not presented in your swift content.",
      "lineNumber":null,
      "cellNumber":null,
      "expression":null
   },
   {
      "etlHistoryID":64,
      "errorType":2,
      "label":"Message #2",
      "message":"{3: User header block} is not presented in your swift content.",
      "lineNumber":null,
      "cellNumber":null,
      "expression":null
   }
]

You can see that the SWIFT 940 file that has been processed from ETL operation id 64 doesn’t have block 1, block 2 and block 3 for both messages in the processed file.

ETLWarnings

This operation returns the warnings logged during the execution of an ETL operation. If no errors are logged, the execution returns empty json array [].
A valid “id” from ETLHistory result must be provided as value for etlHistoryID parameter.
[Get] https://api.bitcurb.com/api/1.0/reports/ETLWarnings?etlHistoryID=<ETLHistoryID>

Field Description can be blank
etlHistoryID Id of ETLHistory table identifying an ETL operation that has been executed No
label String identifying the source of the error No
message Error message No

For example: https://api.bitcurb.com/api/1.0/reports/ETLWarnings?etlHistoryID=73

[
   {
      "etlHistoryID":73,
      "label":"Message #1",
      "message":"C27 - The first two characters of the three character currency code in fields 60a, 62a and 64 must be the same."
   },
   {
      "etlHistoryID":73,
      "label":"Message #2",
      "message":"C27 - The first two characters of the three character currency code in fields 60a, 62a and 64 must be the same."
   },
   {
      "etlHistoryID":73,
      "label":"Message #3",
      "message":"C27 - The first two characters of the three character currency code in fields 60a, 62a and 64 must be the same."
   }
]

You can see that the SWIFT 950 file that has been processed from ETL operation id 73 has a validation warning C27 according the SWIFT standard at message level saying:
C27 – The first two characters of the three character currency code in fields 60a, 62a and 64 must be the same
If you run your ETL template from the BitCurb portal, you will get the warnings with your statistics window indicating the execution of the operation.

Response errors:

In case of error when consuming the report API, the response you will get will be with code 500 (Internal Server Error). The error message will provide Correlation Id to follow up with our support

Unauthorized user or user who is not assigned to licence

You will get 401 error code if you try to consume the report service for a user, who has not been assigned into licence or user who is not valid or active.

You can use the Correlation ID and email address to follow up.

You can get sample reports consumer application from our GitHub repository.