Reconciliation API Reference

The BitCurb Reconciliation API is built around REST and has meaningful resource URLs that hint their purpose. When error conditions occur we use HTTP response status codes to indicate where the problems is – 4XX for client originating errors or 5XX for BitCurb API server errors. When applicable we will return descriptive error messages to indicate and guide you or your client application end users where the problem is, i.e. missing mandatory parameter value.

We utilize the OAuth 2.0 standard authentication protocol to enforce authentication provided that you send us in an initial handshake your unique API client key and API client secret alongside your BitCurb credentials.

JSON is the de facto communication format that BitCurb API is using for both requests and responses.

Our Reconciliation API is well documented with Swagger.
Please, refer to https://api.bitcurb.com/swagger/index.html for details.
Our GitHub repository with code samples and detailed user guide are available and well supported to back you up on your journey with us. We realise that onboarding third party API is challenging and we are here to help.

Authentication

In order to use the BitCurb Reconciliation API you need to first authenticate by sending us your unique API client key, API client secret, username and password. You can find and manage your API client key and secret in our portal under Administration > Client Profile > REST API settings. Keep in mind that it is your responsibility to keep your key and secret safe and don’t publish your code or configuration files if they contain them.
Our API authentication endpoint is https://api.bitcurb.com/connect/token
This is a sample request for authentication using PowerShell:

                    
Invoke-WebRequest –Headers @{"Content-Type"="application/x-www-form-urlencoded"} –Body "grant_type=password&password=YourBitCurbPassword&username=YourBitCurbAccount&client_id=YourAPIClientId&client_secret=YourAPIClientSecret" -Method POST -Uri https://api.bitcurb.com/connect/token
Make sure your parameters that provide for usnername, password, cliend_id and client_secret and they are URL encoded.
Otherwise you may get 400 Bad Request as response to your authentication query.

                    
{
"error": "invalid_grant",
"error_description": "Invalid username or password"
}

If you are successfully authenticated, you will get response similar to the following:

                    
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE1OTM2OTU0MDcsImV4cCI6MTU5MzY5NjYwNywiaXNzIjoiaHR0cDovL3VhdC1hcGkuYml0Y3VyYi5jb20iLCJhdWQiOlsiaHR0cDovL3VhdC1hcGkuYml0Y3VyYi5jb20vcmVzb3VyY2VzIiwiQml0Q3VyYi5BUEkiXSwiY2xpZW50X2lkIjoiNWJmMzcxMDMtYmY0NS00NGRmLWIxNjAtNGQ1ODM5MDljMTEyIiwic3ViIjoiMSIsImF1dGhfdGltZSI6MTU5MzY5NTQwNywiaWRwIjoibG9jYWwiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoic3VwcG9ydEBiaXRjdXJiLmNvbSIsIkNvbnN1bWVyVHlwZSI6IkFwaSIsIlRlbmFudElEIjoiMSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2VtYWlsYWRkcmVzcyI6InN1cHBvcnRAYml0Y3VyYi5jb20iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6InN1cHBvcnRAYml0Y3VyYi5jb20iLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoie1wiSWRcIjoxLFwiVXNlcklkZW50aWZpZXJcIjpcIjczMTliMTI5LTdiZTctNGU1Ny04NThiLTFhM2U2ZDdmOGVmYVwiLFwiVGVuYW50SWRcIjoxLFwiVGVuYW50SWRlbnRpZmllclwiOlwiZWQxYzg4ZTgtOTdjZi00ZTZkLTg5YWEtZDNhYjQ2MjQ3YTNhXCIsXCJFbWFpbFwiOlwic3VwcG9ydEBiaXRjdXJiLmNvbVwiLFwiRmlyc3ROYW1lXCI6XCJCaXRDdXJiXCIsXCJMYXN0TmFtZVwiOlwiQml0Q3VyYlwiLFwiUGhvbmVcIjpudWxsLFwiSXNBZG1pbmlzdHJhdG9yXCI6dHJ1ZSxcIklzVGVuYW50Q29tcGFueU1vZGVcIjpmYWxzZSxcIkNsaWVudFR5cGVcIjoxfSIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vYWNjZXNzY29udHJvbHNlcnZpY2UvMjAxMC8wNy9jbGFpbXMvaWRlbnRpdHlwcm92aWRlciI6IkJpdEN1cmIsIEx0ZC4iLCJzY29wZSI6WyJiaXRjdXJiLmFwaS5hY2Nlc3MiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.bdCY2yk0f_uTQ-mVWYIRz0jc68yEsBfrslaFS4UWX0ivJUy3VRN_-UZOJ6Eo8I0v4661V7JjAssxFla_hPy3JvJE3uMuA83-_glx3FrXUe_Zdi2JH-kPlhBW1QV0EdwOeRoSL6rkVrnetX-IUlAjJKiU52UQ39vFCcnWOUK9OuO0fdSHcedU541pB_N7U-d2Dk0DCT86kb6uvhL0qm1sBFmR7ITB7UUyFgekxYig1jYSpifXBBnLzeFSFWlfzDSbdTdhQegKJFoHrUJe3lP5OwG-l5L5kMvz4DVZEZq77QIF9WgbkyCqpmjDpCqLSzfojZYN8No2tR84WMPh0crXYw",
"expires_in": 1200,
"token_type": "Bearer",
"refresh_token": "598245e769f71c8f4400265f4e99a61061381229392355ec094f77035436d7b3",
"scope": "bitcurb.api.access offline_access"
}

In the JSON you will find an access_token which you need to set in the Authorization header in all subsequent requests. This is an example of the Authorization header:

                    
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE1OTM2OTU0MDcsImV4cCI6MTU5MzY5NjYwNywiaXNzIjoiaHR0cDovL3VhdC1hcGkuYml0Y3VyYi5jb20iLCJhdWQiOlsiaHR0cDovL3VhdC1hcGkuYml0Y3VyYi5jb20vcmVzb3VyY2VzIiwiQml0Q3VyYi5BUEkiXSwiY2xpZW50X2lkIjoiNWJmMzcxMDMtYmY0NS00NGRmLWIxNjAtNGQ1ODM5MDljMTEyIiwic3ViIjoiMSIsImF1dGhfdGltZSI6MTU5MzY5NTQwNywiaWRwIjoibG9jYWwiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoic3VwcG9ydEBiaXRjdXJiLmNvbSIsIkNvbnN1bWVyVHlwZSI6IkFwaSIsIlRlbmFudElEIjoiMSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2VtYWlsYWRkcmVzcyI6InN1cHBvcnRAYml0Y3VyYi5jb20iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6InN1cHBvcnRAYml0Y3VyYi5jb20iLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3VzZXJkYXRhIjoie1wiSWRcIjoxLFwiVXNlcklkZW50aWZpZXJcIjpcIjczMTliMTI5LTdiZTctNGU1Ny04NThiLTFhM2U2ZDdmOGVmYVwiLFwiVGVuYW50SWRcIjoxLFwiVGVuYW50SWRlbnRpZmllclwiOlwiZWQxYzg4ZTgtOTdjZi00ZTZkLTg5YWEtZDNhYjQ2MjQ3YTNhXCIsXCJFbWFpbFwiOlwic3VwcG9ydEBiaXRjdXJiLmNvbVwiLFwiRmlyc3ROYW1lXCI6XCJCaXRDdXJiXCIsXCJMYXN0TmFtZVwiOlwiQml0Q3VyYlwiLFwiUGhvbmVcIjpudWxsLFwiSXNBZG1pbmlzdHJhdG9yXCI6dHJ1ZSxcIklzVGVuYW50Q29tcGFueU1vZGVcIjpmYWxzZSxcIkNsaWVudFR5cGVcIjoxfSIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vYWNjZXNzY29udHJvbHNlcnZpY2UvMjAxMC8wNy9jbGFpbXMvaWRlbnRpdHlwcm92aWRlciI6IkJpdEN1cmIsIEx0ZC4iLCJzY29wZSI6WyJiaXRjdXJiLmFwaS5hY2Nlc3MiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.bdCY2yk0f_uTQ-mVWYIRz0jc68yEsBfrslaFS4UWX0ivJUy3VRN_-UZOJ6Eo8I0v4661V7JjAssxFla_hPy3JvJE3uMuA83-_glx3FrXUe_Zdi2JH-kPlhBW1QV0EdwOeRoSL6rkVrnetX-IUlAjJKiU52UQ39vFCcnWOUK9OuO0fdSHcedU541pB_N7U-d2Dk0DCT86kb6uvhL0qm1sBFmR7ITB7UUyFgekxYig1jYSpifXBBnLzeFSFWlfzDSbdTdhQegKJFoHrUJe3lP5OwG-l5L5kMvz4DVZEZq77QIF9WgbkyCqpmjDpCqLSzfojZYN8No2tR84WMPh0crXYw

All API communication is made over HTTPS.

Get access token from refresh token

If your access token expires, you can request a new one with your refresh token.

                    
Invoke-WebRequest –Headers @{"Content-Type"="application/x-www-form-urlencoded"} –Body "grant_type=refresh_token&refresh_token=YourRefreshToken&client_id=YourAPIClientId" -Method POST -Uri https://api.bitcurb.com/connect/token

Core Operations

  1. Crunch

Starting crunch operations or filtering only of data sets can be done using the following endpoint https://api.bitcurb.com/api/1.0/crunch/run.You need to be authorized to execute this operation by sending a valid Authorization header that includes the token you have received from the OAuth 2.0 authentication operation.

Crunch operations are subject to your 24 hour rolling daily quota. If you exceed the number of records from your licence, the API will reject further processing until this a 24 hour window expires. Check your licence information if you hit this threshold and upgrade it if necessary (licence fee applies).

The crunch JSON request object

                    
{
"$1":[
{
"Id":1,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
"Amount":10.00
}
},
{
"Id":3,
"Fields":{
"Date":"11/13/2016",
"ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67",
"Amount":5.00
}
}
],
"$2":[
{
"Id":2,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
"Amount":10.00
}
},
{
"Id":4,
"Fields":{
"Date":"11/13/2016",
"ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67",
"Amount":5.00
}
}
],
"FieldTypes":{
"Date":"DateTime",
"ItemId":"String"
},
"Filter":{
"Expression":"$1.ItemId == $2.ItemId"
},
"Crunch":{
"Type":"1To1",
"Direction":"$1To$2",
"FieldName":"Amount",
"CreateVariance":"FALSE"
},
"TemplateId":1,
"RuleId":1
}

Attributes:

$1

array

Represents an array object with the first data set
Child attributes
Id

integer

Unique identifier of the item in both data sets.
Fields
object
Represents the attributes that comprise one item in the data set. Your filtering expression is based on these exact fields.
$2
array
Represents an array object with the second data set.
Optional.
Child attributes
Id
integer
Unique identifier of the item in both data sets.
Fields

object

Represents the attributes that comprise one item in the data set. Your filtering expression is based on these exact fields.
FieldTypes

object

Describes the attributes of the data set items – their names and data types.
Filter

object

Represents the filter expression.

The element is optional when TemplateId or RuleId is present otherwise it is mandatory.

Child attributes
Expression

string

The expression used to filter the data sets.

The element is optional when TemplateId or RuleId is present otherwise it is mandatory.

Crunch

object

Represents the crunch definition.

The element is optional when TemplateId or RuleId is present otherwise it is mandatory.

Child attributes
Type

string

Represents the type of crunching algorithm to be used – 1To1 or 1ToMany.
Direction

string

Represents the direction the crunching algorithm to use when comparing the 2 sets of data – $1To$2 or $2To$1.
FieldName

string

The field in the data set item used for the crunch operation.
CreateVariance

boolean

Indicates whether variance items will be created when the crunching algorithm finds partial matches. When false we treat it as if VarianceOperator is “==” and VarianceValue is “0”.
VarianceOperator

string

Specifies which operator to use when resolving the variance difference. Valid operators are <, <=, >, >=, == and !=.

Optional when CreateVariance is false otherwise it is mandatory.

VarianceValue

decimal

The allowed variance value which will be used when resolving the variance difference.

Optional when CreateVariance is false otherwise it is mandatory.

TemplateId

integer

The identifier of the crunching template when executing a template that can be comprised of more than 1 rule in one run.

Optional when Filter and/or Crunch or RuleId are present.

RuleId

integer

The identifier of the crunching rule to execute.

Optional when Filter and/or Crunch or RuleId are present.

The crunch JSON response object when filtering only rule is executed

Contains the subset of the data sets that match the condition in the filtering rule. $1 and $2 are arrays that contain the data set items passed in the JSON request.

The crunch JSON response object when crunching rule is executed

                    
{
"Groups":[
{
"Identifier":"",
"Elements":[

],
"Variance":null
}
]
}
Groups

array

Represents an array object with the crunched groups of items.
Child attributes
Identifier

guid

Unique identifier of the group.
Elements

array

Array containing the identifiers of the items comprising the group.
Variance

decimal

Indicated the variance value if any.

Request/Response for Crunch rules

Here is a sample JSON request:

                    
{
"$1":[
{
"Id":1,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
"Amount":10.00
}
},
{
"Id":3,
"Fields":{
"Date":"11/13/2016",
"ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67",
"Amount":5.00
}
}
],
"$2":[
{
"Id":2,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
"Amount":10.00
}
},
{
"Id":4,
"Fields":{
"Date":"11/13/2016",
"ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67",
"Amount":6.00
}
}
],
"FieldTypes":{
"Date":"DateTime",
"ItemId":"String"
},
"Filter":{
"Expression":"$1.ItemId == $2.ItemId"
},
"Crunch":{
"Type":"1To1",
"Direction":"$1To$2",
"FieldName":"Amount",
"CreateVariance":"FALSE"
}
}

Here we tell the Crunch Engine to find all items that have equal ItemId and use 1 To 1 with $1 to $2 as direction to find all these items with equal CrunchValue in order to group them together. This is what the response will look like:

                    
{
"Groups":[
{
"Identifier":"9bd7a247-4f97-4550-b933-9378e70d9706",
"Elements":[
1,
2
]
}
]
}

In case you want to find groups with variance you can use the following JSON request:

                    
{
"$1":[
{
"Id":1,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
"Amount":10.00
}
},
{
"Id":3,
"Fields":{
"Date":"11/13/2016",
"ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67",
"Amount":5.00
}
}
],
"$2":[
{
"Id":2,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
"Amount":10.00
}
},
{
"Id":4,
"Fields":{
"Date":"11/13/2016",
"ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67",
"Amount":6.00
}
}
],
"FieldTypes":{
"Date":"DateTime",
"ItemId":"String"
},
"Filter":{
"Expression":"$1.ItemId == $2.ItemId"
},
"Crunch":{
"Type":"1To1",
"Direction":"$1To$2",
"FieldName":"Amount",
"CreateVariance":"TRUE",
"VarianceOperator":"<=",
"VarianceValue":1
}
}

The important thing here are these three properties – CreateVariance, VarianceOperator and VarianceValue. There are quite self explanatory and tell the Crunch Engine what to do with variances. In our case it should create groups when the variance is less than or equal to 1. The reponse JSON will be the following:

                    
{
"Groups":[
{
"Identifier":"4c7f2294-93be-49c9-8bb3-8f8488566746",
"Elements":[
1,
2
]
},
{
"Identifier":"bb981879-1267-49ae-bad5-974b11c034e4",
"Elements":[
3,
4
],
"Variance":1
}
]
}

The first group does not have a variance but the second one has and it is represented by the Variance property which tells us what its value is.

Requests/Response for Filter rules

Here is a sample JSON request:

                    
{
"$1":[
{
"Id":1,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
}
}
],
"$2":[
{
"Id":2,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
}
}
],
"FieldTypes":{
"Date":"DateTime",
"ItemId":"String"
},
"Filter":{
"Expression":"$1.ItemId == $2.ItemId"
}
}

Here we tell the crunching engine to find all items that have equal ItemId. This is what the response will look like:

                    
{
"$1":[
{
"Id":1,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
}
}
],
"$2":[
{
"Id":2,
"Fields":{
"Date":"11/13/2016",
"ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
}
}
]
}

Common errors

There are several types of errors that you can receive – authorization, exceeded daily quota and server related.

Authorization errors occur when you cannot be authorized by BitCurb for fulfilling your requested operation. These errors result in a response status code of 401 which stands for Unauthorized error and the error message will be “Permission has not been granted.”.

When you have exceeded your daily quota limit the response status code will be 403 which stands for Forbidden with a message of “You have exceeded your daily quota.”.

If your parameters during authentication are not URL encoded, you may also get Bad Request 400 error.

Server related errors result in response status code of 500 with no specific error message.

Links

You can refer our GitHub repository with code samples and our knowledge base articles to conceive better understanding of how Crunch API could be utilized.