Integration & API.
Introduction
Our expense platform comes in different forms and colours, you might be using our own product that goes under the name Companyexpense or one of our partners white labeled solutions. We use the name Findity Expense Platform or FEP in this documentation when we talk about all products that are based on our platform. FEP is a SaaS platform that is accessed via the web and mobile application and of course accessible via APIs that are described in this documentation. Since our software is more or less built on APIs, many of the platform’s features and functionality are available via external APIs for you to use.
What is an API?
API stands for Application Programming Interface and is a structured and documented way for external parties (customers and partners) to access the Findity Expense Platform from their own systems and environments to exchange data.
What can you do with our API’s?
Basically everything you can do as an administrator in FEP is available as an API endpoint, for instance managing the organisation, users, dimensions, approval structure etc. When working in the FEP user interface you send expense reports to one or more report recipients, these are used to communicate with bookkeeping- and payroll systems. Via the APIs you can instead fetch the report data and update the report status.
One of the most obvious reasons why you should build a solution against our APIs is if you belong to a larger organization with many users and large sets of dimensions data that needs to be updated frequently.
If you are a partner to Findity a common setup is to manage customer and organization setup via API onboarding.
Technology
The FEP API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. We use conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a missing field in JSON request, etc.).
Authentication
The FEP API uses API keys to authenticate all requests. Authentication to the API is performed via providing your token as a HTTP Header value. You do not need to provide a password. All API requests must be made over HTTPS otherwise they will fail.
You can generate an API key (token) from the web client as an organization administrator, and the API needs to be activated on the “Additional services” page.
Example of how the platform can be used with integrations:
.png?width=1000&name=Authentication-workflow%20(1).png)
Resources
Our API documentation is located in Apiary, a separate documentation tool suitable API documentation. See links below.
Findity Expense Admin API
All administrative tasks are found in this API, like managing organizations, users, dimensions, reports etc. This is perfect for tedious tasks or automating the resource update process. This is suitable for large organizations when our user interface isn’t enough. 👉 read more.
Findity Service API
Why not use the power of our platform in your system? You can use our technology to empower your users with the features of Findity Expense Platform. First out is our OCR interpretation receipts analyser. 👉 read more.
What you need to get started
The organization you represent probably already has a relationship with us in some form, as you need something to point at when you start the integration process.
- You need to have a partner or an organisation set up in FEP.
- API account (token key)
If you already are using us in a live production environment or have a more complex integration structure to set up, we have a stage environment that you can use to do initial development and testing. Reach out to customer success or the project manager that can help with the setup of the environment.
Some concepts
Client application
This is normally used for our white label partners or in some cases large customers that are in need of customized high-level configuration and separated environment. A client application gets their own branded apps and clients.
Partner
A partner is an umbrella term used to group several organisations, and can be used for scenarios of a corporation that have several companies or an accounting bureau that manages their customers. An API token can be associated with a partner for easy facilitation of many organizations.
Organization
The actual legal entity of a customer. It holds users, configuration of accounting, approval chain, dimensions, expense reports etc. Most of the admin API calls address a specific organization.
Dimension
A dimension is a financial term used in bookkeeping to keep track of the accounting. We can synchronize dimension values from an external system or they can be created directly in the Findity Platform. Dimensions are used on expenses and provide various functions like approval flows or just generated in the book keeping output from Findity.
Expense
A normal expense is based on a receipt image that is processed by Findity. We automatically populate the expense with category, amounts, date, VAT and currency from the receipt. An expense can also be generated from a corporate card transaction or a mail receipt. We also handle mileage, subsistence allowances and different kinds of benefits.
Reports
A report is a container of one or more expenses. The report is sent in by the end-user, approved by a manager (optional) and finally the administrator generates the book keeping – and/or salary output to an external system.
Report recipient
To be able to create output from our system a report recipient needs to be configured that will dictate format and destination of approved expense reports.
File based
We have recipients that can create many predefined formats for book keeping and salary systems. We have generic recipients that can generate customizable excel and CSV output.
Integration based
We have built API integration to some specific financial systems that synchronize data automatically.
API Recipient
With the API recipient it is possible to automate a solution where the customer fetches reports for salary and/or book keeping data from FEP. The API reports are created in a standardized JSON format which will need to be transformed on the customer side to match the receiving systems import format. The API recipient also has Web hook support to inform the integration that new reports are available.
Clients
Native IOS and Android apps for the end-users. Web application mainly for administrators, but the end-user can also facilitate their expense reporting here.
Single-Sign-On (SSO)
Out of the box Findity Expense Platform provides your organisation with a user repository and password authentication, i.e you create an account with an email address and set a password. If you want to use your own IDP for authentication when logging in to Findity Expense Platform we can set up a connection to it, in this case FEP will act as a Service provider. The IdP connection can be set on all levels in our platform, Client Application, Partner or Organization. Currently we support SAML 2.0 and OpenID Connect protocol.
In order to get SSO to work a user needs to be created in FEP. This user has to belong to an organization that is IdP enabled and an external id has to be set on the user to match the claim from the IdP. NameID for example if using SAML. You have to use the API to set this Id, therefore an integration needs to be set up to manage user federation to FEP.
SSO login flow:
.png?width=1000&name=SSO-workflow%20(1).png)
The user accesses FEP via a browser or mobile app (1) and enters email address. Due to the user belonging to an organisation with an external IdP, a redirect (2) is sent to the users client with a sign in request to the IdP. If the user isn’t already logged in a login page will be displayed. When the IdP decides that the user is signed-in a token is sent back (3) as a response to FEP which is validated and a session is opened in the user’s client.
Developer support
For more information and help contact us at: support@findity.com