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/CrunchRunsProvides 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:
|
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/CrunchRunsDetailsProvides 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:
|
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:
|
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/CrunchRunsGroupsProvides 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.