Zillions API - v0.3

Last revised: 2017-06-26 History Of Changes

Probably we should change all keys in the JSON request bodies to snake_case format, at the moment it's a mixture of snake_case and camelCase...

Base URL
Versioning
Authentication and Environments
Resource Hierarchy
Keywords
General Response Format
API Functions
Resources
List Of Functionalities By Associated Resource
History Of Changes

0. Base URL

The base URL for all API resources and functions is

https://api.zillions.it

All resource and function identifiers in this document are implicitly preceded by the above-mentioned URL.

1. Versioning

To specifiy a version, the keyword version=<required version> must be added to the URL query string, for example /accounts/55?version=v0.2. If the requested version does not exist, the API falls back to the current stable version. If the version=<required version> keyword is omitted in the call to the API, the API uses the current stable version. The currently used version is displayed under the header tag Zillions-API-Version in the HTTP response of the API.

Current Default Version
All Versions

1.1 Current Default Version

The current stable default version is v0.3

1.2 All Versions

v0.2
v0.3

2. Authentication and Environments

Mandatory headers:

zillions-environment (I would like this to be Zillions-Environment in the future)
Zillions-Client-ID
Zillions-Client-Secret

Authentication
Environments
Response For Unsuccessful Authentication

1. Authentication

In order to authenticate an API request, the headers Zillions-Client-ID and Zillions-Client-Secret must be provided with each API call. Zillions-Client-ID is a 20-digit key consisting of numbers and uppercase letters A to F. Zillions-Client-Secret is a 40-digit secret key consisting of numbers and letters. Example curl command:

curl -X GET \
-H "zillions-environment:dev" \
-H "Zillions-Client-ID:<CLIENT-ID>" \
-H "Zillions-Client-Secret:<CLIENT-SECRET>" \
'https://api.zillions.it/users/10/functions'

2. Environments

The Zillions environment (i.e. database) is selected with the zillions-environment header. Possible environments are: demo, test, dev, and prod. Note that not all environments are enabled for each client, by default only the dev environment is enabled. If a client requests an environment which is not yet enabled, the API response is equal to the response for an unsuccessful authentication, see next section. Example curl command:

curl -X GET \
-H "zillions-environment:prod" \
-H "Zillions-Client-ID:<CLIENT-ID>" \
-H "Zillions-Client-Secret:<CLIENT-SECRET>" \
'https://api.zillions.it/users/13333/accounts'

3. Response For Unsuccessful Authentication

{
  "information": {
    "statusCode": 403,
    "statusMessage": "[403] Forbidden.",
    "infoLevel": "Error",
    "internalErrorCode": null,
    "message": "You do not have authorization to request this resource",
    "additionalInfo": null
  },
  "meta": {},
  "data": null
}

3. Resource Hierarchy

TODO

4. Keywords

Global Keywords
Functional Keywords

4.1.1 Versioning

keyword: version=<version>
version format: v0, v0.2, v1
for more info, see Versioning section.

4.1.2 Debugging

keyword: debug=[true/false]
switches on debugging information, which is displayed in the "meta" section of the response.

4.1.3 HTTP Status Code Override

keyword: suppress_http_codes=[true/false]
this option switches off granular HTTP codes
Attention: If this option is enabled, the API responds to every request with status 200 [OK].

4.2 Functional Keywords

NOT YET IMPLEMENTED

5. General Response Format

HTTP Status Codes
A Generic Response

5.1 HTTP Status Codes

200 OK: on success
400 Bad Request: when input fields are missing
403 Forbidden: unsuccessful authentication
404 Not Found: requested resource does not exist
405 Method Not Allowed: the resource does not support the requested HTTP method
422 Unprocessable Entity: invalid input
500 Internal Server Error: if there was an unforeseen error on the server/DB side

5.2 A Generic Response

all responses are in JSON format.

{
  "information": {
    "statusCode": <HTTP status Code>,
    "statusMessage": "[<statusCode>] Corresponding HTTP status message",
    "infoLevel": "OK/Warning/Error",
    "internalErrorCode": <internal error code>,
    "message": "a more detailed status/warning/error message"
      "(intended for the API user)",
    "additionalInfo": "<related link to documentation (TBD)> (TBD)"
  },
  "data": <the output of the DB procedures>,
  "meta": "additional technical information (row counts, ...) (TBD)"
}

6. API Functions

validateInputBulk
insertBulk
createTokenFI - DEPRECATED

6.1 validateInputBulk

URL validateInputBulk
allowed methods: POST
request format: JSON
required keys: usersId, expenseSourcesId, language

Sample Request
Responses

6.1.1 Sample Request

POST validateInputBulk

{
  "usersId": 19271,
  "expenseSourcesId": 1804,
  "language": "en"
}

6.1.2 Responses

If all required data are supplied (usersId, expenseSourcesId, language), the function validateInputBulk always returns with HTTP status 200.

success
failure - missing input data
failure - unforeseen error

success

{
  "information": {
    "statusCode": 200,
    "statusMessage": "[200] OK.",
    "infoLevel": "OK",
    "internalErrorCode": null,
    "message": "Successfully executed validateInputBulk.",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": [
    {
      "expense_sources_id": <expense_sources_id>,
      "trx_number": <transaction number of csv file>,
      "error_flag": true/false,
      "warning_flag": true/false,
      "error_message": <contains row and field name on invalid required field>,
      "warning_message": <contains row and field name on invalid optional field>
    },
    ...,
  ],
  "meta": "additional technical information (row counts, ...) (TBD)"
}

failure - missing input data

{
  "information": {
    "statusCode": 400,
    "statusMessage": "[400] Bad Request.",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Not all required fields present. "\
      "Missing fields: <LIST OF MISSING FIELDS>",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": null,
  "meta": additional technical information (row counts, ...) (TBD)
}

failure - unforeseen error

{
  "information": {
    "statusCode": 500,
    "statusMessage": "[500] Internal Server Error",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Internal Server Error.",
    "additionalInfo": "<related link to documentation>"
  },
  "data": null,
  "meta": "additional technical information (row counts, ...) (TBD)"
}

6.2 insertBulk

URL: insertBulk
allowed methods: POST
request format: JSON
required keys: usersId, expenseSourcesId

Sample Request
Responses

6.2.1 Sample Request

POST insertBulk

{
  "usersId": 19271,
  "expenseSourcesId": 1804
}

6.2.2 Responses

If all required input data (expenseSourcesId, usersId) are present, the function insertBulk always returns with HTTP status 200.

success - expenses inserted
success - no expenses to insert
no success - transactions not valid
no success - expense source for current user does not exist
failure - missing input data
failure - unforeseen error

success - expenses inserted

{
  "information": {
    "statusCode": 200
    "statusMessage": "[200] OK.",
    "infoLevel": "OK",
    "internalErrorCode": null,
    "message": "Successfully inserted expenses",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": {
    "success": true
  },
  "meta": "additional technical information (row counts, ...) (TBD)"
}

success - no expenses to insert

{
  "information": {
    "statusCode": 200,
    "statusMessage": "[200] OK.",
    "infoLevel": "Warning",
    "internalErrorCode": null,
    "message": "No expenses to insert",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": {
    "success": true
  },
  "meta": "additional technical information (row counts, ...) (TBD)"
}

no success - transactions not valid

{
  "information": {
    "statusCode": 200,
    "statusMessage": "[200] OK.",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Transactions are not valid",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": {
    "success": false
  },
  "meta": "additional technical information (row counts, ...) (TBD)"
}

no success - expense source for current user does not exist

{
  "information": {
    "statusCode": 200,
    "statusMessage": "[200] OK.",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Expense source for current user does not exist",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": {
    "success": false
  },
  "meta": "additional technical information (row counts, ...) (TBD)"
}

failure - missing input data

{
  "information": {
    "statusCode": 400,
    "statusMessage": "[400] Bad Request.",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Not all required fields present." \
      "Missing fields: <LIST OF MISSING FIELDS>",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": null,
  "meta": "additional technical information (row counts, ...) (TBD)"
}

failure - unforeseen error

{
  "information": {
    "statusCode": 500,
    "statusMessage": "[500] Internal Server Error",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Internal Server Error.",
    "additionalInfo": "<related link to documentation>"
  },
  "data": null,
  "meta": "additional technical information (row counts, ...) (TBD)"
}

6.3 createTokenFI - DEPRECATED

DEPRECATED! USE POST TO users/ID/accounts SEE THE CORRESPONDING SECTION

URL: createTokenFI
allowed methods: POST
request format: JSON
required keys: returnUrl

So far, this function only uses the returnUrl key. Also, it connects to a fake bank with a temporary user. The mapping of saltedge customer ids and account ids to our user ids and account ids will be added gradually and documented here.

Sample Request
Responses

6.3.1 Sample Request

{
  "usersId": 10,
  "fiId": 1,
  "returnUrl": "https://www.zillions.it"
}

6.3.2 Responses

success - token created
failure - no token created
failure - missing input data
failure - unforeseen error

success - token created

{
  "information": {
    "statusCode": 200,
    "statusMessage": "[200] OK.",
    "infoLevel": "OK",
    "internalErrorCode": null,
    "message": "Successfully created Token",
    "additionalInfo": "<related link to documentation>"
  },
  "meta": {
    "error_class_saltedge": null,
    "error_message_saltedge": null
  },
  "data": {
    "success": true,
    "usersId": 10,
    "fiId": 1,
    "return_url": "https://www.zillions.it",
    "token": <TOKEN>,
    "connect_url": "https://www.saltedge.com/connect?token=<TOKEN>",
    "expires_at": "2017-12-04T11:07:38Z"
  }
}

failure - no token created

{
  "information": {
    "statusCode": 422,
    "statusMessage": "[422] Unprocessable Entity.",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Could not create Token",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": {
    "success": false,
    "usersId": 10,
    "fiId": 1,
    "return_url": "https://www.zillions.it",
    "token": null,
    "connect_url": null,
    "expires_at": null
  },
  "meta": {
    "error_class_saltedge": <saltedge error class>,
    "error_message_saltedge": <saltedge error message>
  }
}

failure - missing input data

{
  "information": {
    "statusCode": 400,
    "statusMessage": "[400] Bad Request.",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Not all required fields present." \
      "Missing fields: <LIST OF MISSING FIELDS>",
    "additionalInfo": "<related link to documentation> (TBD)"
  },
  "data": null,
  "meta": "additional technical information (row counts, ...) (TBD)"
}

failure - unforeseen error

{
  "information": {
    "statusCode": 500,
    "statusMessage": "[500] Internal Server Error",
    "infoLevel": "Error",
    "internalErrorCode": (TBD),
    "message": "Internal Server Error.",
    "additionalInfo": "<related link to documentation>"
  },
  "data": null,
  "meta": "additional technical information (row counts, ...) (TBD)"
}

7. Resources

users
functions
accounts

7.1 users

NOT YET IMPLEMENTED

7.2 functions

URL: users/<users_id>/functions/<function_id>

GET
POST

7.2.1 GET

List Securable Functions
List Detailed Function Permissions

7.2.1.1 List Securable Functions

List all securable functions for a given user, together with his current usage plan.
URL: users/<users_id>/functions

Query Keywords
Example

Query Keywords

execution_time=<DATETIME string>: optional: this specifies the execution time. If omitted, the current datetime is used.

Example

Example request:

GET users/12345/functions?execution_time=2017-12-02T13:00

Response:

"information": {
      "statusCode": 200,
      "statusMessage": "[200] OK.",
      "infoLevel": "OK",
      "internalErrorCode": null,
      "message": "[200] OK.",
      "additionalInfo": "<link to documentation>"
    },
    "meta": {},
    "data": [
      {
        "function_id": 1,
        "function_name": "DocumentUpload",
        "enabled": true,
        "function_description": "",
        "limit_type": "zillions_auth.docs_year",
        "function_limit": 100,
        "execution_time": "2017-12-02T12:00:00.000Z",
        "current_plan": 1,
        "users_id": "12345"
      },
      {
        "function_id": 1,
        "function_name": "DocumentUpload",
        "enabled": true,
        "function_description": "",
        "limit_type": "zillions_auth.doc_size_mb",
        "function_limit": 5,
        "execution_time": "2017-12-02T12:00:00.000Z",
        "current_plan": 1,
        "users_id": "12345"
      },
      {
        "function_id": 1,
        "function_name": "DocumentUpload",
        "enabled": true,
        "function_description": "",
        "limit_type": "zillions_auth.total_storage_gb",
        "function_limit": 0.3,
        "execution_time": "2017-12-02T12:00:00.000Z",
        "current_plan": 1,
        "users_id": "12345"
      }

    ]

7.2.1.2 List Detailed Function Permissions

Lists detailed permissions for a securable function, specifed by function_id or function_name, and the user's usage_plan.
URL: users/<users_id>/functions/<function_id OR function_name>

Query Keywords
Example

Query Keywords

execution_time=<datetime string>: optional. Specifies the execution time. If omitted, the current datetime is used. Example: execution_time=2017-11-20%2011:00.
execution_value=<execution value>: optional. Specifies the queried execution value. Example: execution_value=3.0.
limit_type=<limit type>: optional (?). Specifies the queried limit type. Example: limit_type=zillions_auth.doc_size_mb.

Example

Example request:

GET users/12345/functions/1?execution_value=4.3&limit_type=zillions_auth.doc_size_mb

or:

GET users/12345/functions/DocumentUpload?execution_value=4.3\
&limit_type=zillions_auth.doc_size_mb

Response:

"information": {
      "statusCode": 200,
      "statusMessage": "[200] OK.",
      "infoLevel": "OK",
      "internalErrorCode": null,
      "message": "[200] OK.",
      "additionalInfo": "<link to documentation>"
    },
    "meta": {},
    "data": {
      "function_id": 1,
      "function_name": "DocumentUpload",
      "enabled": true,
      "function_message": "ok",
      "limit_allowed": 1,
      "limit_message": "ok",
      "execution_time": "2017-12-06T12:04:28.000Z",
      "execution_value": 4.3,
      "limit_type": "zillions_auth.doc_size_mb",
      "function_limit": 5,
      "current_plan": 1,
      "users_id": "12345"
    }

7.2.2 POST

7.3 accounts

URL: users/<users_id>/accounts
allowed methods: POST, GET
request format: JSON

GET
POST
Refresh Account

7.3.1 GET

7.3.2 POST

required keys: fis_id, return_url

Sample Request
Responses

7.3.2.1 Sample Request

POST users/12971/accounts

{
 "fis_id": 66,
 "return_url": "https://my.zillions.it"
}

The same request can be supplied multiple times. The corresponding responses then give information about the status of the request. Alternatively, the request_id returned in the response of the first request can be used to check the status of the request in the update_requests table in the import database. When all accounts and transactions for the corresponding request are imported into the database, update_requests.request_status='complete'.

7.3.2.2 Responses

token created
repeated request - processing
repeated request - completed
failure - token could not be created
failure - unforeseen error

token created

HTTP status: 202

{
  "information": {
    "statusCode": 202,
    "statusMessage": "[202] Accepted.",
    "infoLevel": "OK",
    "internalErrorCode": null,
    "message": "Successfully created Token",
    "additionalInfo": "<link to documentation>"
  },
  "meta": {},
  "data": {
    "users_id": "12971",
    "fis_id": "66",
    "request_id": 10,
    "return_url": "https://my.zillions.it",
    "token": "https://www.some.url/<TOKEN>",
    "connect_url": "<TOKEN>",
    "expires_at": "2018-03-01T11:42:40Z",
    "request_status": "pending"
  }
}

repeated request - processing

HTTP status: 409

{
  "information": {
    "statusCode": 409,
    "statusMessage": "[409] Conflict.",
    "infoLevel": "Error",
    "internalErrorCode": null,
    "message": "The update request for user 12971 with FI 66 is processing at the moment.",
    "additionalInfo": "<link to documentation>"
  },
  "meta": {},
  "data": {
    "users_id": "12971",
    "fis_id": "66",
    "request_id": 10,
    "return_url": "https://my.zillions.it",
    "token": null,
    "connect_url": null,
    "expires_at": null,
    "request_status": "processing"
  }
}

repeated request - completed

HTTP status: 303

{
    "information": {
        "statusCode": 303,
        "statusMessage": "[303] See Other.",
        "infoLevel": "OK",
        "internalErrorCode": null,
        "message": "The update request for user 12971 with FI 66 is already complete.
          All accounts and transactions are imported.
          See imported accounts under
  'https://api.zillions.it/accounts?creation_type=accounts&created_by=10&version=v0.3'
          and imported transactions under
  'https://api.zillions.it/transactions?creation_type=accounts&created_by=10&version=v0.3'.",
        "additionalInfo": "<link to documentation>"
    },
    "meta": {},
    "data": {
        "users_id": "12971",
        "fis_id": "66",
        "request_id": 10,
        "return_url": "https://my.zillions.it",
        "token": null,
        "connect_url": null,
        "expires_at": null,
        "request_status": "complete",
        "url_accounts":
  "https://api.zillions.it/accounts?creation_type=accounts&created_by=10&version=v0.3",
        "url_transactions":
  "https://api.zillions.it/transactions?creation_type=accounts&created_by=10&version=v0.3"
    }
}

failure - token could not be created

HTTP status: 422

{
  "information": {
    "statusCode": 422,
    "statusMessage": "[422] Unprocessable Entity.",
    "infoLevel": "Error",
    "internalErrorCode": null,
    "message": "Could not create Token.",
    "additionalInfo": "<link to documentation>"
  },
  "meta": {},
  "data": {
    "users_id": "12971",
    "fis_id": "66",
    "request_id": null,
    "return_url": "https://my.zillions.it",
    "token": null,
    "connect_url": null,
    "expires_at": null,
    "request_status": "failed"
  }
}

failure - unforeseen error

HTTP status: 500

{
 "information": {
   "statusCode": 500,
   "statusMessage": "[500] Internal Server Error",
   "infoLevel": "Error",
   "internalErrorCode": (TBD),
   "message": "Internal Server Error.",
   "additionalInfo": "<related link to documentation>"
 },
 "data": null,
 "meta": "additional technical information (row counts, ...) (TBD)"
}

3. Refresh Account

URL: users/<users_id>/accounts/<accounts_id>/refresh
allowed methods: POST
request format: JSON

POST

7.3.3.1 POST

required keys: return_url

Sample Request
Responses

7.3.3.1.1 Sample Request

POST users/12967/accounts/67/refresh

{
 "return_url": "https://my.zillions.it"
}

7.3.3.1.2 Responses

token created
repeated request - processing
failure - token could not be created
failure - unforeseen error

token created

HTTP status: 202

{
  "information": {
    "statusCode": 202,
    "statusMessage": "[202] Accepted.",
    "infoLevel": "OK",
    "internalErrorCode": null,
    "message": "Successfully created Token",
    "additionalInfo": "<link to documentation>"
  },
  "meta": {},
  "data": {
    "users_id": "12971",
    "fis_id": "66",
    "request_id": 10,
    "return_url": "https://my.zillions.it",
    "token": "https://www.some.url/<TOKEN>",
    "connect_url": "<TOKEN>",
    "expires_at": "2018-03-01T11:42:40Z",
    "request_status": "pending"
  }
}

repeated request - processing

HTTP status: 409

{
  "information": {
    "statusCode": 409,
    "statusMessage": "[409] Conflict.",
    "infoLevel": "Error",
    "internalErrorCode": null,
    "message": "The update request for user 12971 with FI 66 is processing at the moment.",
    "additionalInfo": "<link to documentation>"
  },
  "meta": {},
  "data": {
    "users_id": "12971",
    "fis_id": "66",
    "request_id": 10,
    "return_url": "https://my.zillions.it",
    "token": null,
    "connect_url": null,
    "expires_at": null,
    "request_status": "processing"
  }
}

failure - token could not be created

HTTP status: 422

{
  "information": {
    "statusCode": 422,
    "statusMessage": "[422] Unprocessable Entity.",
    "infoLevel": "Error",
    "internalErrorCode": null,
    "message": "Could not create Token.",
    "additionalInfo": "<link to documentation>"
  },
  "meta": {},
  "data": {
    "users_id": "12971",
    "fis_id": "66",
    "request_id": null,
    "return_url": "https://my.zillions.it",
    "token": null,
    "connect_url": null,
    "expires_at": null,
    "request_status": "failed"
  }
}

failure - unforeseen error

HTTP status: 500

{
 "information": {
   "statusCode": 500,
   "statusMessage": "[500] Internal Server Error",
   "infoLevel": "Error",
   "internalErrorCode": (TBD),
   "message": "Internal Server Error.",
   "additionalInfo": "<related link to documentation>"
 },
 "data": null,
 "meta": "additional technical information (row counts, ...) (TBD)"
}

8. List of Functionalities By Associated Resource

users
functions
accounts

8.1 users

8.2 functions

List Securable Functions
List Detailed Function Permissions

List Securable Functions

List all securable functions for a given user, together with his current usage plan.
more info: List Securable Functions

List Detailed Function Permissions

Lists detailed permissions for a securable function, specifed by function_id or function_name, and the user's usage_plan.
more info: List Detailed Function Permissions

8.3 accounts

Create a Token to import account and transaction data
Refresh Account and Transaction Data

Create a Token to import account and transaction data

Create a Token to connect a user with users_id to a bank with fis_id
Returns the corresponding request_id with which the status of the request can be checked
If the request_status is complete, all accounts and transactions are imported
Multiple requests also give information about the request status
more info: Create a Token to import account and transaction data

Refresh Account and Transaction Data

Create a Token to refresh the account with accounts_id of a user with users_id
Returns the corresponding request_id with which the status of the request can be checked
If the request_status is complete, all new account and transaction data are imported
more info: Refresh Account and Transaction Data

9. History Of Changes

2018-06-26

updated accounts section (refresh)

2018-03-05

updated accounts section
restructuring

2018-03-01

added accounts section
createTokenFI is now deprecated

2017-12-20

changed base URL
updated versioning section

2017-12-19

added authentication section
updated HTTP status codes

2017-12-06

restructuring
added functions resource
added keywords section
added versioning section
added list of functionalities

2017-12-04

added HOC