Working with Expenses

Overview

In this guide, you will learn:

• Possible operations that can be performed on an expense
• Meaning of the response fields

Before you get started

Before you get started, you’ll need to ensure that you know the employment_id

Creating an Expense

The Remote API has the capability to create, list, and show already approved expenses. Each expense belongs to an employment, has an amount in a given currency, the date it was incurred, and a receipt file.

When creating an expense in a different currency of the employment, for instance, a €100.00 expense that belongs to an American employment, it is possible to send the following request:

1curl --location --request POST 'https://gateway.remote-sandbox.com/v1/expenses' \
2--header 'Authorization: Bearer <your token>' \
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "employment_id": "7db936d5-ea9b-4e97-a1f3-4d94ca39c294",
6    "amount": 10000,
7    "category": "education_training",
8    "currency": "EUR",
9    "expense_date": "2023-01-10",
10    "receipt": {
11        "content": "UGVyaW9kI...DAsMCwwLDEwMCwwCg==",
12        "name": "receipt.pdf"
13    },
14    "tax_amount": 0,
15    "timezone": "Etc/UTC",
16    "title": "Giving Constructive Feedback Training",
17    "reviewed_at": "2023-02-10T00:00:00Z"
18}'

The response will look like this:

1{
2    "data": {
3        "expense": {
4            "amount": 10000,
5            "category": "education_training",
6            "converted_amount": 10735,
7            "converted_currency": {
8                "code": "USD",
9                "name": "United States Dollar",
10                "symbol": "$"
11            },
12            "converted_tax_amount": 0,
13            "currency": {
14                "code": "EUR",
15                "name": "European Euro",
16                "symbol": "€"
17            },
18            "employment_id": "7db936d5-ea9b-4e97-a1f3-4d94ca39c294",
19            "expense_date": "2023-01-10",
20            "id": "c26257a7-1cb5-4cd1-bf76-3ed0a389979c",
21            "invoice_period": null,
22            "notes": null,
23            "reason": null,
24            "reviewed_at": "2023-02-10",
25            "reviewer": {
26                "user_email": "jane+manager@remote.com",
27                "user_id": "2f73619f-4970-4c23-a7bb-3d110a7e6cf2",
28                "user_name": "Jane Smith"
29            },
30            "status": "approved",
31            "tax_amount": 0,
32            "title": "Giving Constructive Feedback Training 5"
33        }
34    }
35}

In this example, we created an expense with the source currency in EUR but the amount was converted to USD, since it is an American worker. If the expense is in the same currency as the country the employment was created, the amount will be the same.

Response Fields

As shown, the response object contains some fields that weren't explicitly required in the creation. Next, they're presented in more detail.

Currencies

To create an expense, the request parameters must have the cost in the currency that the expense was paid. That can also be referred to as the source currency.

The response object for the create, show, and list expenses requests, returns the amount and currency of the expense in both source currency (amount and currency fields) and in the converted currency (converted_amount and converted_currency fields), which is the currency the employee or contractor will be paid in. The same definitions apply to the tax fields (tax_amount and converted_tax_amount).

Receipt

The receipt field represents the receipt of the purchase, which is required to create an expense. The file name and the content encoded in base64 define a receipt to be attached to the expense. The receipt is necessary to create an expense; however, it's not yet available for download through the Remote API.

To get the base64-encoded file content via the command line, you can run:

1$ base64 -i path/to/file.pdf
2JVBERi0xLjQKJcOkw7zDtsP922jjaA+hXY1Wh1aNVo...Kc3RhcnR4cmVmCjEyNzg3CiUlRU9GCg==

Revision

The reviewer_id and reviewed_at fields are optional when creating an expense. If the approver of the expense is a user in Remote, it is possible to provide the user_id for the reviewer_id field. If the value is not provided, it will default to the user that generated the API access token. The same applies to the reviewed_at field. If the timestamp is not provided, it will be set to the timestamp of when the request was done.

To search for possible user_ids to set the reviewers, query the /company-managers endpoint.

[partners] You can check the documentation for it here.

[customers] You can check the documentation for it here.

Other operations

There's also the GET /expenses endpoint, to query the list of expenses of all employments that belong to the company, and the GET /expenses/:id endpoint, to show information of a single expense. Other operations, for example, deleting, modifying, or creating an expense reimbursement request that has not been approved, are not yet supported. However, please contact Remote at api-support@remote.com if you need a feature that is not available.