Download OpenAPI specification:Download
This documentation describes how to create expenses and claims. It also describes how to manage expense types, rates and attachments.

Please see our support centre for user guides on expenses.
List all expense types.
The requesting user must have the create-expenses permission.
Array of objects | |
object |
{- "data": [
- {
- "id": 159,
- "name": "Car parking",
- "order_id": 5
}
], - "meta": {
- "pagination": {
- "total": "string",
- "count": "string",
- "per_page": "string",
- "current_page": "string",
- "total_pages": "string",
- "links": {
- "next": "string",
- "previous": "string"
}
}
}
}Create a new expense type.
The requesting user must have the edit-expense-settings permission.
| name | string |
| position | integer <int32> |
| id | integer <int64> |
| name | string |
| order_id | integer <int32> |
{- "name": "Car parking",
- "position": 5
}{- "id": 159,
- "name": "Car parking",
- "order_id": 5
}Update an existing expense type.
The requesting user must have the edit-expense-settings permission.
| id required | string |
| name | string |
| position | integer <int32> |
| id | integer <int64> |
| name | string |
| order_id | integer <int32> |
{- "name": "Car parking",
- "position": 5
}{- "id": 159,
- "name": "Car parking",
- "order_id": 5
}Delete an existing expense type.
The requesting user must have the edit-expense-settings permission.
| id required | string |
No content
{ }List all expense rates for the specified organisation.
The requesting user must have the create-expenses permission.
Array of objects | |
object |
{- "data": [
- {
- "id": 0,
- "description": "string",
- "short_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "rate": 0.45,
- "passenger_rate": 0.05,
- "max_miles": 300,
- "order_id": 0,
- "created_at": "2023-01-01 00:00:00",
- "updated_at": "2023-01-05 14:40:25"
}
], - "meta": {
- "pagination": {
- "total": "string",
- "count": "string",
- "per_page": "string",
- "current_page": "string",
- "total_pages": "string",
- "links": {
- "next": "string",
- "previous": "string"
}
}
}
}Create a new expense rate for the specified organisation.
The requesting user must have the edit-expense-settings permission.
| short_name | string <= 255 characters |
| start_date | string <date> |
| end_date | string <date> |
| description | string |
| rate | number <float> |
| passenger_rate | number <float> |
| max_miles | integer <int32> |
| order_id | integer <int32> |
{- "short_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "description": "string",
- "rate": 0.45,
- "passenger_rate": 0.05,
- "max_miles": 300,
- "order_id": 0
}{- "id": 0,
- "description": "string",
- "short_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "rate": 0.45,
- "passenger_rate": 0.05,
- "max_miles": 300,
- "order_id": 0,
- "created_at": "2023-01-01 00:00:00",
- "updated_at": "2023-01-05 14:40:25"
}Update an existing expense rate for the specified organisation.
| id required | string |
| id | integer <int64> |
| description | string |
| short_name | string <= 255 characters |
| start_date | string <date> |
| end_date | string <date> |
| rate | number <float> |
| passenger_rate | number <float> |
| max_miles | integer <int32> |
| order_id | integer <int32> |
| created_at | string <date-time> |
| updated_at | string <date-time> |
{- "id": 0,
- "description": "string",
- "short_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "rate": 0.45,
- "passenger_rate": 0.05,
- "max_miles": 300,
- "order_id": 0,
- "created_at": "2023-01-01 00:00:00",
- "updated_at": "2023-01-05 14:40:25"
}Update an existing expense rate for the specified organisation.
| id required | string |
| short_name | string <= 255 characters |
| start_date | string <date> |
| end_date | string <date> |
| rate | number <float> |
| passenger_rate | number <float> |
| max_miles | integer <int32> |
| order_id | integer <int32> |
| id | integer <int64> |
| description | string |
| short_name | string <= 255 characters |
| start_date | string <date> |
| end_date | string <date> |
| rate | number <float> |
| passenger_rate | number <float> |
| max_miles | integer <int32> |
| order_id | integer <int32> |
| created_at | string <date-time> |
| updated_at | string <date-time> |
{- "short_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "rate": 0.45,
- "passenger_rate": 0.05,
- "max_miles": 300,
- "order_id": 0
}{- "id": 0,
- "description": "string",
- "short_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "rate": 0.45,
- "passenger_rate": 0.05,
- "max_miles": 300,
- "order_id": 0,
- "created_at": "2023-01-01 00:00:00",
- "updated_at": "2023-01-05 14:40:25"
}List all expenses for the authenticated user.
The user must have the create-expenses permission.
| userId required | string Authenticated user ID. This is a required field. |
| claimed | boolean Example: claimed=true Only retrieve claimed or not claimed expenses. If not supplied, both claimed and not claimed expenses will be returned |
| o | string Example: o=d Order by specific column (default is date). Use |
| s | string Example: s=amount Column to use for sorting (ordering). Default is date. Available columns for sorting are: |
| include | string Enum: "user" "type" "rate" "attachments" "role" "role.roleProfile" Example: include=type Available expense includes (comma separated list) |
Array of objects | |
object |
{- "data": [
- {
- "id": 0,
- "amount": 0.1,
- "description": "string",
- "submitted": "2019-08-24",
- "claimed": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "date": "2019-08-24",
- "miles": 0.1,
- "passengers": 0,
- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "user_id": 0,
- "type_id": 0,
- "rate_id": 0
}
], - "meta": {
- "pagination": {
- "total": "string",
- "count": "string",
- "per_page": "string",
- "current_page": "string",
- "total_pages": "string",
- "links": {
- "next": "string",
- "previous": "string"
}
}
}
}Create a new expense.
The expense will be assigned to the user who created it.
Please note that the type.id is a required field. You can get the list of expense types by calling the GET /expenses/types endpoint.
The requesting user must have the create-expenses permission.
| amount | number <float> |
| description | string |
| submitted | string <date> |
| date | string <date> |
| miles | number <float> |
| passengers | integer <int32> |
object | |
object | |
object |
{- "amount": 10.5,
- "description": "Car parking",
- "submitted": "2023-01-01",
- "date": "2019-08-24",
- "miles": 0.1,
- "passengers": 2,
- "type": {
- "id": 20
}, - "rate": {
- "id": 5
}, - "role": {
- "id": 5215
}
}{- "id": 0,
- "amount": 0.1,
- "description": "string",
- "submitted": "2019-08-24",
- "claimed": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "date": "2019-08-24",
- "miles": 0.1,
- "passengers": 0,
- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "user_id": 0,
- "type_id": 0,
- "rate_id": 0
}Get an existing expense for the authenticated user.
The requesting user must have the create-expenses permission.
| userId required | string User ID. This is a required field. |
| id required | string Expense ID. This is a required field. |
| include | string Enum: "user" "type" "rate" "attachments" "role" "role.roleProfile" Example: include=type Available expense includes (comma separated list) |
| id | integer <int64> |
| amount | number <float> |
| description | string |
| submitted | string <date> |
| claimed | boolean |
| created_at | string <date-time> |
| updated_at | string <date-time> |
| date | string <date> |
| miles | number <float> |
| passengers | integer <int32> |
object (UserBase) | |
| user_id | integer <int64> |
| type_id | integer <int64> |
| rate_id | integer <int64> |
{- "id": 0,
- "amount": 0.1,
- "description": "string",
- "submitted": "2019-08-24",
- "claimed": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "date": "2019-08-24",
- "miles": 0.1,
- "passengers": 0,
- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "user_id": 0,
- "type_id": 0,
- "rate_id": 0
}Update an existing expense for the authenticated user.
Please note that you cannot modify a claimed expense.
The requesting user must have the create-expenses permission.
| amount | number <float> |
| description | string |
| date | string <date> |
| miles | number <float> |
| passengers | integer <int32> |
object | |
object | |
object |
| id | integer <int64> |
| amount | number <float> |
| description | string |
| submitted | string <date> |
| claimed | boolean |
| created_at | string <date-time> |
| updated_at | string <date-time> |
| date | string <date> |
| miles | number <float> |
| passengers | integer <int32> |
object (UserBase) | |
| user_id | integer <int64> |
| type_id | integer <int64> |
| rate_id | integer <int64> |
{- "amount": 10.5,
- "description": "Car parking",
- "date": "2019-08-24",
- "miles": 0.1,
- "passengers": 2,
- "type": {
- "id": 20
}, - "rate": {
- "id": 5
}, - "role": {
- "id": 5215
}
}{- "id": 0,
- "amount": 0.1,
- "description": "string",
- "submitted": "2019-08-24",
- "claimed": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "date": "2019-08-24",
- "miles": 0.1,
- "passengers": 0,
- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "user_id": 0,
- "type_id": 0,
- "rate_id": 0
}Delete an existing expense for the authenticated user.
Please note that you cannot delete a claimed expense.
The requesting user must have the create-expenses permission.
No content
{ }Get a list of attachments for a specific expense
| id | integer ID of the file |
object The image thumbnails |
| id | integer ID of the file |
| original_name | string Original name of the file |
| file_size | integer File size (bytes) |
| mime | string File mime type |
object The image thumbnails | |
| signed_url | string <uri> Signed URL for the file |
{- "id": 45645,
- "thumbnails": { }
}{- "id": 45645,
- "original_name": "fuel-receipt.pdf",
- "file_size": 231256,
- "mime": "application/pdf",
- "thumbnails": {
},
}Get an attachment for a specific expense for specified user.
| userId required | string User ID |
| id required | string Expense ID |
| fileId required | string File (attachment) ID |
| id | integer ID of the file |
| original_name | string Original name of the file |
| file_size | integer File size (bytes) |
| mime | string File mime type |
object The image thumbnails | |
| signed_url | string <uri> Signed URL for the file |
{- "id": 45645,
- "original_name": "fuel-receipt.pdf",
- "file_size": 231256,
- "mime": "application/pdf",
- "thumbnails": {
},
}Attach an existing file for an existing expense for the given user.
Please note that the file must be uploaded before attaching it to an expense.
The file ID must be provided in the request path.
The file must be uploaded using the POST /api/files endpoint. In the body, use file:BLOB as the file content. In the response, you will receive an id which you can use to attach the file to an expense.
Also please note that there is no POST endpoint for expense attachments. You have to upload the file first (as outlined above) and then attach it (associate) to an expense via PUT request.
| userId required | string User ID |
| id required | string Expense ID |
| fileId required | string File (attachment) ID |
| id | integer ID of the file |
| original_name | string Original name of the file |
| file_size | integer File size (bytes) |
| mime | string File mime type |
object The image thumbnails | |
| signed_url | string <uri> Signed URL for the file |
{- "id": 45645,
- "original_name": "fuel-receipt.pdf",
- "file_size": 231256,
- "mime": "application/pdf",
- "thumbnails": {
},
}Delete an existing expense for the authenticated user. The file ID must be provided in the request path.
| userId required | string User ID |
| id required | string Expense ID |
| fileId required | string File (attachment) ID |
No content
{ }List claims for all managed users.
Please note the list of user claims will be restricted to the users that
the authenticated API user is able to manage.
The authenticated API user must have the Approve claims permission to
access this endpoint.
| approved | boolean Example: approved=true Only retrieve approved or not approved claims. If not supplied, both approved and not approved claims will be returned. |
| submitted | boolean Example: submitted=true Only retrieve submitted or not submitted claims (see description above). If not supplied, both submitted and not submitted claims will be returned. |
| user | string Example: user=123,124,125 Only retrieve claims created by the specified user IDs. |
| assignee | string Example: assignee=456,457,458 Only retrieve claims assigned to the specified user IDs (claim authorisers). |
| o | string Example: o=d Order by specific column (default is created_at). Use |
| s | string Example: s=amount Column to use for sorting (ordering). Default is created_at. Available columns for sorting are: |
| include | string Enum: "user" "expenses" "assignedTo" "approvedBy" "role" "role.roleProfile" Example: include=expenses Available claim includes (comma separated list) |
Array of objects | |
object |
{- "data": [
- {
- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "assignedTo": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approvedBy": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approved": true,
- "approved_at": "2019-08-24T14:15:22Z",
- "submitted": true,
- "submitted_at": "2019-08-24T14:15:22Z",
- "amount": 0.1,
- "notes": "string",
- "rejection_note": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "meta": {
- "pagination": {
- "total": "string",
- "count": "string",
- "per_page": "string",
- "current_page": "string",
- "total_pages": "string",
- "links": {
- "next": "string",
- "previous": "string"
}
}
}
}List all claims for the specified user.
Please note submitted and submitted_date will only be set when
the claim is submitted if expenses_submission_email organisation
setting is set to a valid email address.
The expenses email can be set in /portal/admin/organisation/expenses/settings for users with edit-expense-settings permission.
Claims cannot be deleted, instead they should be rejected.
| userId required | string User ID. This is a required field. |
| submitted | boolean Example: submitted=true Only retrieve submitted or not submitted claims (see description above). If not supplied, both submitted and not submitted claims will be returned. |
| from | string <date> Example: from=2024-01-01T00:00:00.000Z Filter claims created after this date |
| to | string <date> Example: to=2024-06-30T00:00:00.000Z Filter claims created before this date |
| o | string Example: o=d Order by created_at column. Use |
| include | string Enum: "user" "expenses" "assignedTo" "approvedBy" "role" "role.roleProfile" Example: include=expenses Available claim includes (comma separated list) |
Array of objects | |
object |
{- "data": [
- {
- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "assignedTo": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approvedBy": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approved": true,
- "approved_at": "2019-08-24T14:15:22Z",
- "submitted": true,
- "submitted_at": "2019-08-24T14:15:22Z",
- "amount": 0.1,
- "notes": "string",
- "rejection_note": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "meta": {
- "pagination": {
- "total": "string",
- "count": "string",
- "per_page": "string",
- "current_page": "string",
- "total_pages": "string",
- "links": {
- "next": "string",
- "previous": "string"
}
}
}
}Create a new claim for the authenticated user.
Expenses can be added to the claim by providing an array of expenses in the expenses field in the
body of the request. These expenses must be unclaimed and associated with the same role.
object User ID to assign the claim to | |
| notes | string |
Array of objects Expense IDs to be claimed |
{- "assignedTo": {
- "id": 20
}, - "notes": "string",
- "expenses": [
- {
- "id": 1242
}
]
}{- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "assignedTo": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approvedBy": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approved": true,
- "approved_at": "2019-08-24T14:15:22Z",
- "submitted": true,
- "submitted_at": "2019-08-24T14:15:22Z",
- "amount": 0.1,
- "notes": "string",
- "rejection_note": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Get an existing claim.
| userId required | string User ID. This is a required field. |
| id required | string Claim ID. This is a required field. |
| include | string Enum: "user" "expenses" "assignedTo" "approvedBy" "role" "role.roleProfile" Example: include=expenses Available claim includes (comma separated list) |
object (UserBase) | |
object (UserBase) | |
object (UserBase) | |
| approved | boolean |
| approved_at | string <date-time> |
| submitted | boolean |
| submitted_at | string <date-time> |
| amount | number <float> |
| notes | string |
| rejection_note | string |
| created_at | string <date-time> |
| updated_at | string <date-time> |
{- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "assignedTo": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approvedBy": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approved": true,
- "approved_at": "2019-08-24T14:15:22Z",
- "submitted": true,
- "submitted_at": "2019-08-24T14:15:22Z",
- "amount": 0.1,
- "notes": "string",
- "rejection_note": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Update an existing claim. The approve-claims or self-approve-claims permission is required to approve a claim.
| userId required | string User ID. This is a required field. |
| id required | string Claim ID. This is a required field. |
object User ID to assign the claim to | |
| notes | string |
| rejection_note | string Reason for rejecting the claim |
| approved | boolean Approves the claim by the current user. The claim must not have been previously rejected. |
| approval_note | string Reason for approving the claim |
| submitted | boolean Submits the claim if the claim has been approved. The claim must not have been previously submitted. |
| submitted_date | string <date-time> Date the claim was submitted. Defaults to the current date. |
object (UserBase) | |
object (UserBase) | |
object (UserBase) | |
| approved | boolean |
| approved_at | string <date-time> |
| submitted | boolean |
| submitted_at | string <date-time> |
| amount | number <float> |
| notes | string |
| rejection_note | string |
| created_at | string <date-time> |
| updated_at | string <date-time> |
{- "assignedTo": {
- "id": 20
}, - "notes": "string",
- "rejection_note": "string",
- "approved": true,
- "approval_note": "string",
- "submitted": true,
- "submitted_date": "2019-08-24T14:15:22Z"
}{- "user": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "assignedTo": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approvedBy": {
- "id": 46485,
- "display_name": "John Smith",
- "title": "Mr",
- "can_manage": true,
- "role_name": "Volunteer",
- "team_name": "Kent",
- "status": {
- "id": "1",
- "name": "Active",
- "contactable": true
}
}, - "approved": true,
- "approved_at": "2019-08-24T14:15:22Z",
- "submitted": true,
- "submitted_at": "2019-08-24T14:15:22Z",
- "amount": 0.1,
- "notes": "string",
- "rejection_note": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}