Welcome to the Aventus Platform API. # Authentication The Aventus Platform API implements OAuth 2.0, this allows users to grant 3rd party applications full or partial access to their account data without sharing their login credentials. The process involves several steps: 1. Acquire an access token 2. Send the access token in the Authorization header with each request. eg: `Authorization: Bearer ACCESS_TOKEN` Find out more about implementing authentication at https://docs.aventusplatform.com/docs/authentication. # Data Types All API request and response bodies are formatted as JSON. The following table outlines our data types and default formatting. |Datatype|JSON Datatype|Description| |-----|-----|-----| |String|String|A sequence of zero or more Unicode characters. Strings are delimited with double-quotation marks and support a backslash escaping syntax.| |UUID|String|All IDs are represented in UUID (guid) format.
Format: `00000000-0000-0000-0000-000000000000`| |Number|Number|Whole numbers
Example: `3245`| |Float|Number|Decimals/numbers. The decimal point is required.
Format: `0.0`
Example: `0.34` || |Boolean|Boolean|Either of the values true or false
Example: `true` `false`| |Array|Array|An ordered list of zero or more values, each of which may be of any type. Arrays use square bracket notation and elements are comma-separated.
Example: `["one",2,false]` `[]` `["one"]`| |Dictionary|Object|An unordered collection of key-value pairs
Example:`{"key1":"value1","key2":2}`| |Date|String|Provided as a string, formatted using [ISO 8601 Date formatting](https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates)
Format: `YYYY-MM-DD`
Example: `"2018-12-01"` => 1st December 2018| |DateTime|String|Provided as a string, formatted using [ISO 8601 Time formatting](https://en.wikipedia.org/wiki/ISO_8601#Times). The offset is optional and the default timezone is UTC.
Formats: `YYYY-MM-DDThh:mm:ssZ` `YYYY-MM-DDThh:mmZ` `YYYY-MM-DDThh:mm:ss±hh:mm`
Example: `"2018-05-23T15:35:45Z"`| # Response Envelope All API responses, including errors, return a `ResponseEnvelope` object (unless otherwise specified). |Name|DataType|Description| |-----|-----|-----| |data|object|The response data| |time|int|The time taken to execute the request| |error|int|The error code, if the request was unsuccessful.
For a successful response error will be -1| |error_description|string|The description of the error| |successful|bool|True for a successful request, otherwise false.| |validationErrors|ValidationError Array|Array of validation errors (if any)| ```json { "data":{}, "time":150, "error":-1, "error_description":null, "successful":true, "validationErrors": [] } ``` # Errors The API returns standard HTTP status codes. Successful API requests will return status code `200 (OK)`. If an error does occur, additional error information may also be returned in the `error` & `error_description` properties in the `ResponseEnvelope` object. |Status Code|Error| |-----|-----| |400|Bad Request - Please check the request to fix the error| |401|Unauthorized - You’re not authorized to access the requested endpoint, or your access token has expired| |403|Forbidden - The access token does not contain the scopes required to access the requested endpoint| |404|Not Found - The requested endpoint or resource does not exist| |429|Too Many Requests - Too many requests have been sent in a given amount of time| |500|Internal Server Error - Something went wrong| **Example Error** ```json { "data":null, "time":0, "error":1006, "error_description":"Validation failed", "successful":false, "validationErrors": [ { "message":"The 'FirstName' cannot be null", "propertyIndentifier":"FirstName" } ] } ``` ### Validation Errors Validation Errors will return a 400 response with `error:1006`, the `validationErrors` property will contain the list of validation errors. ### Authentication Errors Any errors returned during the Authentication flow will return the following error format ```json { "error":"string", "error_description":"string" } ``` ## Error Codes Unsuccessful API requests return additional error information in the `error` and `error_description` properties. Below is a list of possible error codes that can be returned. |Error|Description| |-----|-----| |0|Something went wrong on our side| |1|You're not authorised to access the requested resource| |2|The requested resource does not exist| |3|You're not authorised to access the requested resource| |4|Invalid action requested| |1000|The request contains an invalid value| |1006|A validation error has occurred, check the `validationErrors` for further details| |1014|The voucher code provided is invalid| |1016|A mid-term adjustment is not possible| |1017|The finance agreement could not be created| |1018|The bank account details provided are incorrect| |1023|The policy with the requested id has been cancelled| |1024|The quote with the requested id has expired| |1025|The quote with the requested id has already been purchased| |1026|The API domain does not exist| |1027|Invalid API tenant| |1028|The api version requested is invalid| |1035|The specified amount is less than the minimum amount allowed.| |1038|There was an error adding the payment method| |1055|There was a configuration error| |2020|The finance agreement could not be updated for a mid term adjustment. Mid term adjustments can only be purchased 24 hours after the initial policy purchase| # Rate Limiting The Aventus Platform API is rate limited to prevent abuse by third-party services. If your requests are being rate limited, the API will return HTTP status code 429. If you find your requests are continuously being rate-limited please contact us. ```json { "data": {}, "time": 0, "error": 429, "error_description": "HTTP Error 429: Too Many Requests", "successful": false, "validationErrors": [] } ```