> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expensify

## After this article

You'll be able to connect Expensify to Lumos to ingest user, policy, and policy role data, and optionally provision user access. This integration supports both syncing and provisioning.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes\* | User account records. Create Account and Update Account are supported, and **Employee ID** (`employeeID`) is a mappable field on Create Account |
| Policy | Resource | Yes | No | Policies in Expensify |
| Policy Role | Permission | Yes | Yes\* | Roles granting access to policies |

| Deprovisioning Action | Type | Description |
| - | - | - |
| Delete | User | Deletes an Expensify user |

* User creation, user update, and policy role assignment are only available on the `Expensify Provisioning` version (\*)

## Required plan and roles

* **Expensify credentials:** you'll generate a **partnerUserID** and **partnerUserSecret** pair from the Expensify integrations tools page.
* **Account ID:** an identifier used to scope operations for your tenant. Contact your Expensify administrator or check your Expensify account settings to obtain this value.

## Read-only access vs provisioning

**Is read-only possible?** No. The connector authenticates with a single **partnerUserID** and **partnerUserSecret** pair, and that same credential is used for both syncing and provisioning.

**What full provisioning requires.** The **partnerUserID** and **partnerUserSecret** pair generated from the Expensify integrations tools page, plus your Expensify **Account ID**. Follow the steps below to connect.

**Watch out for.** Expensify identifies employees by an `employeeID`. Lumos uses the value you map on Create Account, and when an Expensify employee has no `employeeID`, Lumos generates one before writing, so write actions no longer fail on a missing ID. There are two versions of the integration, Expensify and Expensify Provisioning; make sure the correct one is selected.

## Instructions

<Accordion title="Expensify">
  Choosing the App Instance Identifier

  * Please choose a unique identifier for this Expensify integration. Example: `lumos-expensify-1`. This serves as a way to differentiate multiple instances of Expensify integrations from each other.

  Generating Credentials

  1. Visit [<u>https://www.expensify.com/tools/integrations/</u>](https://www.expensify.com/tools/integrations/) and log in.
  2. Follow the instructions to setup Integration Server Access.
  3. Copy the value of **partnerUserID** and paste it in the appropriate box below.
  4. Copy the value of **partnerUserSecret** and paste it in the appropriate box below.
  5. If you wish to filter the expenses retrieved by category, enter a comma-separated list of category names with quotes around each name. For example: "Software","Software Services","Software Infrastructure","Data Feeds","Dues & Subscriptions" If you leave this empty, all expenses will be retrieved.
</Accordion>

<Accordion title="Expensify Provisioning">
  **Gather Partner User Secret**

  * To obtain your Partner User Secret follow these steps:
    * Navigate to [https://www.expensify.com/tools/integrations/](https://www.expensify.com/tools/integrations/) Log in with your Expensify account credentials You will be provided with a partnerUserID and partnerUserSecret pair Paste the partnerUserSecret value below IMPORTANT: You won't be shown this secret again, so save it immediately when generated.

  **Gather Partner User ID** 

  * To obtain your Partner User ID follow these steps:
    * Navigate to [https://www.expensify.com/tools/integrations/](https://www.expensify.com/tools/integrations/) Log in with your Expensify account credentials You will be provided with a partnerUserID and partnerUserSecret pair Paste the partnerUserID value below

  **Confirm Unique ID** 

  * Provide a unique ID that will be used to identify the application. This can be self generated.
</Accordion>

**Phase 1: Gather your Expensify credentials**

1. Navigate to [https://www.expensify.com/tools/integrations/](https://www.expensify.com/tools/integrations/).
2. Log in with your Expensify account credentials.
3. You'll be provided with a **partnerUserID** and **partnerUserSecret** pair.
4. Save the **partnerUserSecret** immediately. Expensify won't show it again after it's generated.
5. Obtain your **Account ID** (your unique Expensify account identifier). It should be a stable identifier that doesn't change for the lifetime of your Expensify account.

**Phase 2: Connect in Lumos**

1. Go to **Settings > Integrations and choose the appropriate version.**
2. Paste the **partnerUserID**, **partnerUserSecret**, and **Account ID** into the matching fields.
3. Connect the integration.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Invalid credentials error when connecting.** Re-check the **partnerUserID** and **partnerUserSecret** values. Expensify returns "Invalid credentials" for a bad credential pair, and the connector classifies this as an authorization error.

**Older tasks failed with "Employee ... is missing employee ID".** Before September 2026, assign, unassign, and delete actions required the Expensify employee record to carry an `employeeID` and failed when it was missing. Lumos now generates an `employeeID` for employees that have none, so the error no longer occurs. Retry any task that failed with this message.