Getting started

When working with our Expense API all requests are oriented around a specific user. Meaning that all calls need to be done with an API key that is on the user level. See this guide on how to do that.

Your first request

When you have the access token of a user you are ready for your first call. We will use the /me endpoint to get information on the logged-in user. If all goes well you should get a similar response as the one below.

{
    "id": "3ba28c4f546baad6128b80fb94060999",
    "email": "[email protected]",
    "firstName": "Benny",
    "lastName": "Johansson",
    "defaultCurrency": "SEK",
    "bankAccountNumber": "1234567890",
    "IBAN": "NL02ABNA9965356246",
    "BIC": "HANDSESS",
    "language": "sv_SE",
    "formattingRegion": "sv_SE",
    "address": {
        "id": "8ab28c4f8b6beed5018b80fb94010727",
        "countryCode": "SE"
    },
    "settings": {
        "bompenger": {
            "autopassActivated": false,
            "lastFuelTypeChoice": "Diesel"
        },
        "app": {
            "appTheme": "Light",
            "automaticallyOpenCameraView": true,
            "promptForSubmitExpenseReport": true,
            "promptForSubmitExpense": true,
            "promptForApproveExpenseReport": true,
            "promptForApproveExpense": true
        }
    }
}

Big congrats if this worked for you. In that case, you have successfully authenticated as the user and accessed the user information, which means the user is available in the system. You are ready for the next lesson.

Getting more info about the user

We need to check the surroundings for more info to present the correct actions for the user. First, let's see if the user is an employee, this means that we check what company the user belongs to. In our system, we call that organization and we will use that term from now. Note that a user can have multiple employments, hence the user can belong to multiple organizations.

Head to the get-organization endpoint to see where the user works. The id of the organization is needed in basically all the calls within the Expense API, save it. Below you see the response of a user belonging to the Prestige Worldwide organization.

{
    "meta": {
        "total": 1,
        "count": 1
    },
    "data": [
        {
            "id": "8ab28cb36900800c016900cbcab4003e",
            "name": "Prestige Worldwide",
            "approvalEnabled": false
        }
    ]
}

You can also include meta.permissions to see what actions are allowed for the user. Speaking of what is allowed, the next endpoint to call is to check which expense types are available in an organization. You can expect something like this in return.

{
    "meta": {
        "total": 3,
        "count": 3
    },
    "data": [
        {
            "type": "ReceiptVerification",
            "name": "Expense",
            "iconUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e8d5acac0018d5ad37c530002",
            "canCreate": true
        },
        {
            "type": "CarSpecification",
            "name": "Mileage",
            "iconUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e8751fbf201875344b2f801a8",
            "canCreate": true
        },
        {
            "type": "SubsistenceAllowance",
            "name": "Per diem",
            "iconUrl": "https://stage-expense.findity.com/api/resources/8ab28c4e8d5a93f3018d5abd2c750099",
            "canCreate": true
        }
    ]
}

Create expenses

There are two ways of creating expenses, you can address the "Create expense" endpoint directly, which is a more generic and static setup compared to the other way which is using the fields endpoint. The fields endpoint is a helper function that guides the client (that you are building) on what fields are available, data types to use, what is mandatory, etc. Since our platform is highly customizable, and every customer organization can have a different setup when it comes to which expense types are available, and which categories can be used by the employees. The client asks the field endpoint how to render the expense view for the user, and allows your client to be dynamic as our expense platform is, this is the preferred way of building against our Expense API. Our recommendation is that you use the field structure to help you build the best solution for your client when there is a user interacting with the endpoints. It handles the unexpected and errors in a more structured way than the first option.

Here are some articles showing the two different options to create all available expense types.

Mileage (standard format)