API Documentation

Request/Response

All request and response formats are JSON. We currently do not support XML for the following reasons:

  • Lack of consistency for parsing data types among third party XML libraries and utilities
  • Serialization/Deserialization Performance
  • Verbosity
  • Bandwidth usage

Versioning

Versioning is determined by the API Key (routes do not include the version). The CorePro Admin site will display the API Key for each version currently available.

Developers should expect that new elements may be added to the JSON data structure for a current version at any time. Elements will not be removed, renamed (amount -> tranAmount), or change case (amount -> AMOUNT) in a given version of the API. The properties in the JSON data structure will typically be in alphabetical order; however, this is not guaranteed.

Retrieving Resources with the HTTP GET Method

You can retrieve a representation of a resource by GETting its url. The easiest way to do this is to copy and paste a URL into your web browser's address bar.

Creating or Updating Resources with the HTTP POST Method

Creating or updating a resource involves performing an HTTP POST to a resource URI. In POST, you represent the properties of the object you wish to update as form urlencoded key/value pairs.

  • NOTE: When updating a resource, it is possible to leave a property value untouched. Simply do not pass the property name in the JSON payload, or pass the property name with its value as null

Data Format Guidelines

All date properties will be in the ISO 8601 date format (i.e., 2013-10-03T13:38:44.754-05:00). Any dates passed into the API are expected to be UTC time and dates returned from the API will be in the time zone of the bank where the deposits are being held. Only exception to this rule would be properties such as birthDate which will contain zeroes for the time elements.

All decimal values have at most 2 digits of precision. The exception is any interest rate properties, which have up to 11 digits of precision.

Boolean values are returned as true or false.

Culture (in /customer) is a unique name for each culture based on RFC 4646 . The name is a combination of an ISO 639-1 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. Currently the CorePro API is only supported in the US. The default culture for every program is en-US, but additional cultures may be added on a per-program basis.

Country codes will follow the ISO 3166-1 alpha 3 standard as this is what is utilized on passports.

Property Naming Guidelines

Property Name Data Type Comment
Ends with Id 32-bit integer Exceptions:
  • transactionId is a 64-bit integer
  • taxId is a string
Ends with Amount decimal

2 digits of precision to the right of the decimal

Ends with Balance decimal 2 digits of precision to the right of the decimal
Ends with Date datetime ISO 8601 date format. e.g.: 2013-10-03T13:38:44.754-05:00
Ends with Percent decimal

2 digits of precision to the right of the decimal

Begins with is boolean Only possible values are true and false
Begins with Interest decimal 11 digits of precision to the right of the decimal
None of the above string

Possible HTTP Response Status Codes

HTTP Code Description
200 OK: The request was successful, we retrieved or updated the resource.
201 CREATED: The request was successful, we created the resource.
400 BAD REQUEST: The request was unsuccessful due to malformed syntax or failed validation.
401 UNAUTHORIZED: The supplied credentials, if any, are not sufficient to perform the requested action.
404 NOT FOUND: The requested resource was not found.
405 METHOD NOT ALLOWED: Your requested HTTP method is not allowed.
429 TOO MANY REQUESTS: Your application has attempted too many API requests within the designated call limit timeframe.
500 SERVER ERROR: Internal server error. CorePro has an application or configuration issue.
503 SERVICE UNAVAILABLE: CorePro is temporarily unavailable (e.g.: maintenance window is in effect). Please try again later.

API Call Limit

API calls are subject to the default limit of 15 requests per second and exceeding this limit will result in all endpoints returning an HTTP status code of 429. Limits are per API key. If the limit is exceeding then the API Key will be blocked for the remainder of the sample period. If an API key continually hits the call limit we reserve the right to permanently block the key and to charge a fee to unblock the key.

To determine the API call amount we monitor the traffic over a sample period. If the traffic results in a particular API key reaching 80% of the limit (i.e., 12 if the limit is 15) over the sample period then the responses will start to contain a throttle node which contains useful information on how close you are to reaching the call limit.

Response Format

CorePro uses a simple envelope concept to wrap all responses. Envelope definition is as follows.

Property Description
data The data requested. Differs depending upon the route called. May be an object, a list of objects, or null. If null, data property will be absent from the response. Will never be a string, number, or date.
errors A list of error Objects objects. If no error occurred, this will be an empty list. A single request can cause multiple errors. Each error object contains a code property and a message property. The message property may change depending upon the culture, request parameter values, etc. code is guaranteed to never change, and that value should be used to drive logic within your application.
requestId A globally unique string that identifies this particular request. Useful for troubleshooting errors or tracking down problems historically. It is recommended this value be stored somewhere on the caller's end when logging request/response pairs as it enables CorePro support to easily identify the exact request associated with your issue.
status The overall status of the response. Reflects exactly the http status. Useful if your client code only wants to inspect the actual body, and not the status portion of the raw http response.
throttle Throttling information emitted only if you are past 80% of the throttling limit, or if you have surpassed the throttling limit.

Here is an example response body from a CorePro request.

200
{ 
    "data":
    {
        [
            {
                "accountId": 12345,
                "name": "My savings account",
                "type": "Savings"
            }
        ]
    },
    "errors":[],
    "requestId":"2dd82a44-02b0-49cb-94e3-ca454bcdd276",
    "status":200,
    "throttle": 
    {
        "maximumRequestsPerPeriod": 15,
        "periodEndsAt": "2013-10-03T13:38:44.754+00:00",
        "periodLengthInSeconds": 10,
        "requestsRemainingInPeriod": 2,
        "secondsUntilNextPeriod": 5
    }
}

Ready to start a conversation?

Email Us