API Overview

The IF API is a REST-based API, however, we extended the REST approach slightly to give you the opportunity to harness the full power of the IF Platform.

The main purpose of the IF API is to allow you to manage your resources on the platform by providing:

• control over how workflows are executed
• the ability to orchestrate underlying connections/integrations
• the ability to perform business functions with the minimum number of API calls
• a simple and understandable interface for each business function
• an infrastructure to allow the API to progressively evolve without breaking changes

While a standard REST architectural approach allows clients to manipulate resources via resource state representations, we encountered two challenges:

• it was not possible to provide IF API clients with a mechanism to manipulate how state transitions are executed (workflows)
• it was not possible to provide IF API clients with the ability to orchestrate underlying integrations (CONNECT)

Both situations were not possible without exposing each workflow and orchestration combination as an endpoint. Therefore we extended plain resource representations with container objects which are explained in Section 4.

1. GENERAL RULES

Usage of HTTPS, SSL, and TLS v1.2 or above is required.

2. URL STRUCTURE

The URL structure of IF API is as below:

https://[sandbox-]api.integrated.finance/<version>/<instance-id>/<resource>[/sub-resource|identifier]*

version is the API version.
instance-id is the identifier of your instance.
resource represents the module's main resource. (e.g. clients, accounts etc.)
sub-resource represents a resource dependent to main resource
identifier identifier for the resource or sub-resource

3. HTTP METHODS

Standard HTTP methods are used to manipulate resources via the IF API and how are they used are listed below:

GET: is used for retrieving data.
POST: is used for creating resources, and invoking corresponding workflows where applicable.
PATCH: is used for updating resources, and invoking corresponding workflows where applicable.
DELETE: is used for deleting resources, and invoking corresponding workflows where applicable.

Fully replacing objects via the API is not possible as some parts/fields of objects are not meant to change.

4. REQUEST & RESPONSE BODIES

The global structure for API requests & response bodies (for HTTP methods POST, PATCH) is as below:

{
  "workflow": {...}, // 1
  "data": {...}, // 2
  "connect": {...}, // 3
  "metadata": {...} // 4
}

4.1 Workflow Container Object: "workflow"

• Requests: The workflow related data will be accepted inside this container object.
• Responses: The resulting workflow data will be returned inside this container object.

4.2 Data Container Object: "data"

• Requests: The resource to process will be accepted inside this container object.
• Responses: The resulting resource will be returned inside this container object.

Contents of the data container object can differ depending on the workflow choices.

4.3 Connect Container Object: "connect"

• Requests: Data related to the orchestration of integrations will be accepted inside this container object.
• Responses: The resulting data related to the orchestration of integrations will be returned inside this container object.

4.4 Metadata Container Object: "metadata"

• Requests: Currently not used, but documented in case of future usage.
• Responses: The information related to data such as paging information will be returned inside this container object.

Contents of all container objects differ for each module while there is consistency between module endpoints. A detailed explanation of container objects can be found within each module’s designated documentation.

5. QUERY PARAMATERS

Query parameters are only used on GET endpoints. Some of the globally used query parameters are:

pageSize: used at endpoints that list certain data, to identify the size of the page requested.
page: used in endpoints that list certain data, to identify which page you wish to retrieve.
sort: used in endpoints that lists certain data, to identify the sorting of the listed data.