Skip to main content

Introduction

As a media partner at AVICA Group, you have several options to integrate your existing systems with us. One of these options is to use our APIs to synchronize conversions and applications between your systems.

Basics​

All our APIs are based on REST technology and assume JSON format for both request and response data. Some endpoints may be subject to rate limits (429) and IP restrictions. If you encounter issues related to these limits, please don't hesitate to contact your account manager.

Servers are running in UTC timezone and assumes all timestamps delivered to the server are UTC.

Response codes

  • HTTP 403: Access not allowed (API key or IP restriction)
  • HTTP 429: Rate limit
  • HTTP 422: Validation errors.
  • HTTP 200: Request was successful.

Response headers​

Content-Type: application/json

Base Url​

https://api.financeservice.io/v1

Authentication​

You can find your API key at the media partner portal under account settings. Do not hesitate to contact us if you have a suspecion that your API key has been compromised. Also reach out to your account manager if you feel the need to use multiple api keys e.g. for different systems.

To authenticate, include your API key in the standard HTTP authentication header with the username Bearer.

Authentication: Bearer API-KET-GOES-HERE

Response format​

Endpoints wrap the response items in a JSON meta data object similar to the one you see below. The data key can contain all type of valid JSON values including arrays, objects and scalar values. The success key is true when the http response code is in the 2XX range and false otherwise.

{
    "items": 0,
    "success": true,
    "page": 1,
    "last_page": true,
    "data": []
}

Paging​

All endpoints can return maximum 1.000 items per request. The size of each page can be controlled by the query parameter page_size while the page to be queried can be controlled through the page parameter.

The last_page in the response meta data can be used to query all available items by scrolling through the pages in the API. The page query parameter should be incremented by one until the last_page variable is false.

Filtering Query​

Endpoints used to fetch data from the AVICA servers utilize a filtering engine that allows you to query only the data you need. The query consists of a JSON document that should be posted to the endpoint.

The queries consist of three layers: one ruleset -> one/many rule groups -> one/many rules. A query can contain one ruleset only, but it can contain multiple rule groups. Rule groups are separated by OR, while the rules within each rule group are separated by AND.

Rulegroups are separated by OR while the rules within each rulegroup are separated by AND

Rule format​

A rule is an array containing exactly three fields in the correct order: 1) field name, 2) operator, and 3) comparison value.

This rule checks that the field columnName1 has a value greater than 10.

['columnName1', 'greaterThan', 10]

Operators​

The available operators are

  • equal (=)
  • notEqual (!=)
  • greaterThan (>=)
  • lessThan (<)
  • greaterThanEqual (>=)
  • lessThanEqual (<=)
  • in (item exists in list)
  • notIn (item does not exists in list)
  • contains (non case sensitive string search)
  • notContains (non case sensitive string search)

Examples​

Example #1​

One ruleset, one rule group and two rules.

[{
    ['columnName1', 'greaterThanEqual', 15],
    ['columnName2', 'lessThan', 25]
}]

Which translates into this sql-like query

columName1 >= 15 AND columnName2 <= 25

Example #2​

One ruleset consisting of two rule groups that each has two rules.

[{
    ['columnName1', '=', 'value1'],
    ['columnName2, '>', numericValue1]
},{
    ['columnName1' '=', 'alternativeValue1'],
    ['columnName2' '>' numericValue2]
}]

This translates into the following (SQL alike) conditions where items are matched if ...

(
    columnName1 = 'value1' AND
    columnName2 >= numericValue1
) OR (
    columnName1 = 'alternativeValue1' AND
    columnName2 >= numericValue2
)