API Reference

The BitCurb 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.

Authentication

In order to use the BitCurb 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 endpoint is https://portal.bitcurb.com/api/1.0/

This is a sample request for authentication using curl:

curl –header “Content-Type: application/x-www-form-urlencoded” –data 
“client_id=YourClientKey&client_secret=YourClientSecret&username=YourUsername&password=YourPassword&grant_type=password” https://portal.bitcurb/token

You will receive the following JSON response:

{
  "access_token": "VAOcH495YWe94IaWneCrkn2b712v4ejFGTa0V3eBz0-BSEhjE7XhYgpMJdy3a_
GXIPaVGIlljqa_BHCwpI-VplCBr_J_gjAOQqjthyRcckbA45gpwpzyT4smvwdq4Gzl7Ozogg0p0EOhkWC
Uedisud7HAUuwjO3ZhhbDu1MpIIkLRjC2VWUg8a-Kz25QDvnE6KZlqGCFpPiX7Hv0efo9AFVfUqC6sy3a
Yn8OSy3lSE8m8v-0F8e0uwO4n16NxvHj2nLkmJ-EeUVMVgH_pEBAtlzNCiHcBegqzFOWfAf1cd01LHpexf
jV7ktyO284WOkIlUsknZQPzKh1aFQFXIj5GyEG
TXaP4bO1PaYH0SxUCQpbiS1C_LTgVe0OatS4QiJpzfhOF6pCFj37mHnItu3tHD
-dHzHB7ri16ycuuQc1GUkZAo_mY-CiS7XNWFUbfC7S9HQPGLOIKbfcG4tS9YSPlWh1lRW4ov_TJ2o86xu1
PV0Wz4Gxk1WGBbUBS9YgyfzDP3A
07ypCCRAaaisXlQxOVMCdYj_NpoQz_OKCtvFfbJmDAvR4nJTnoMnk31d1
C4hEJHC3R6QFXh5EFZFItet7
eA_ZgajyHcFuel7dA5iZ2kef6aljY4IyKbz5ATQanyktebOu-Ugr1y9y2V0m_qNMVXpPGd1yHKICF8zjP
l8TpefccnRKujz20deg4T6EckAkaDjwjFb-dThxU_qUWs0PIA",
 
  "token_type": "bearer",
  "expires_in": 1799,
  "refresh_token": "3062dc56fdbd4d358f59a715cc87527e",
  "refresh_token_expires_in": 432000,
  "as:client_id": "YourClientKey",
  "userName": "YourUsername",
  ".issued": "Mon, 24 Apr 2017 21:07:48 GMT",
  ".expires": "Mon, 24 Apr 2017 21:37:48 GMT"

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 VAOcH495YWe94IaWneCrkn2b712v4ejFGTa0V3eBz0
-BSEhjE7XhYgpMJdy3a_GXIPaVGIlljqa_BHCwpI-VplCBr_J_gjAOQqjthyRcck
bA45gpwpzyT4smvwdq4Gzl7Ozogg0p0EOhkWCUed
isud7HAUuwjO3ZhhbDu1MpIIkLRjC2VWUg8a-Kz25QDvnE6KZlqGCFpPiX7Hv0ef
o9AFVfUqC6sy3aYn8OSy3lSE8m8v-0F8e0uwO4n16NxvHj2nLkmJ-EeUVMVgH_pE
BAtlzNCiHcBegqzFOWfAf1cd01LHpexfjV7ktyO284WOkIlUsknZQ
PzKh1aFQFXIj5GyEGTXaP4bO1PaYH0SxUCQpbiS1C_LTgVe0OatS4QiJpzfhOF6
pCFj37mHnItu3tHD-dHzHB7ri16ycuuQc1GUkZAo_mY-CiS7XNWFUbfC7S9HQPG
LOIKbfcG4tS9YSPlWh1lRW4ov_TJ2o86xu1PV0Wz4Gxk
1WGBbUBS9YgyfzDP3A07ypCCRAaaisXlQxOVMCdYj_NpoQz_OKCtvFfbJmDAvR4
nJTnoMnk31d1C4hEJHC3R6QFXh5EFZFItet7eA_ZgajyHcFuel7dA5iZ2kef6a
ljY4IyKbz5ATQanyktebOu-Ugr1y9y2V0m_qNMVXpPGd1yHKICF8zjPl8Tpefccn
RKujz20deg4T6EckAkaDjwjFb-dThxU_qUWs0PIA

All API communication is made over HTTPS.

Core Operations

  1. Crunch

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

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

The crunch JSON request object

{
   "$1":[
      {
         "Id":1,
         "CrunchValue":10.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
            "Amount":10.00
         }
      },
      {
         "Id":3,
         "CrunchValue":5.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67",
            "Amount":5.00
         }
      }
   ],
   "$2":[
      {
         "Id":2,
         "CrunchValue":10.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202",
            "Amount":10.00
         }
      },
      {
         "Id":4,
         "CrunchValue":5.00,
         "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.
CrunchValue

decimal

The value that is used by the crunching algorithm to find matching pairs.

Optional (not applicable to filtering rules).

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.
CrunchValue

decimal

The value that is used by the crunching algorithm to find matching pairs.

The element is not applicable to filtering rules but mandatory for crunching rules.

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

{
   "$1":[

   ],
   "$2":[

   ]
}

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,
         "CrunchValue":10.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
         }
      },
      {
         "Id":3,
         "CrunchValue":5.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67"
         }
      }
   ],
   "$2":[
      {
         "Id":2,
         "CrunchValue":10.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
         }
      },
      {
         "Id":4,
         "CrunchValue":6.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67"
         }
      }
   ],
   "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,
         "CrunchValue":10.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
         }
      },
      {
         "Id":3,
         "CrunchValue":5.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67"
         }
      }
   ],
   "$2":[
      {
         "Id":2,
         "CrunchValue":10.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"5F95B5E6-FA4E-4C72-9800-346349B40202"
         }
      },
      {
         "Id":4,
         "CrunchValue":6.00,
         "Fields":{
            "Date":"11/13/2016",
            "ItemId":"2743FF09-C6DE-4315-9A76-58D2477BDE67"
         }
      }
   ],
   "FieldTypes":{
      "Date":"DateTime",
      "ItemId":"String"
   },
   "Filter":{
      "Expression":"$1.ItemId == $2.ItemId"
   },
   "Crunch":{
      "Type":"1To1",
      "Direction": "$1To$2",
      "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.”.

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.