# Expensify

Expensify is an expense management platform that automates receipt scanning, expense reporting, and reimbursement. The Sling Expensify connector extracts data from the Expensify Integration Server API, supporting policies, categories, tags, employees, reports, and individual expenses.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `partner_user_id` **(required)** -> Your Expensify Integration Partner User ID
* `partner_user_secret` **(required)** -> Your Expensify Integration Partner User Secret

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your API Credentials

1. Log in to your [Expensify](https://www.expensify.com/) account
2. Go to **Settings** > **Workspaces** > select your workspace
3. Navigate to **Accounting** or **Connections** section
4. Under **Integration Partner Credentials**, generate or view your:
   * **Partner User ID** (typically in the format `aa_yourname_domain_com`)
   * **Partner User Secret** (a long hex string)

{% hint style="warning" %}
**Important:** You need administrator access to the workspace to generate API credentials. The credentials provide access to all policies/workspaces the account can access.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set EXPENSIFY type=api spec=expensify secrets='{ partner_user_id: aa_yourname_domain_com, partner_user_secret: your_secret_here }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export EXPENSIFY='{ type: api, spec: expensify, secrets: { partner_user_id: "aa_yourname_domain_com", partner_user_secret: "your_secret_here" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  EXPENSIFY:
    type: api
    spec: expensify
    secrets:
      partner_user_id: "aa_yourname_domain_com"
      partner_user_secret: "your_secret_here"
```

**With anchor date for historical data:**

```yaml
connections:
  EXPENSIFY:
    type: api
    spec: expensify
    secrets:
      partner_user_id: "aa_yourname_domain_com"
      partner_user_secret: "your_secret_here"
    inputs:
      anchor_date: "2023-01-01"
```

## Replication

Here's an example replication configuration to sync Expensify data to a PostgreSQL database:

```yaml
source: EXPENSIFY
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: expensify.{stream_name}

streams:
  # sync all endpoints
  '*':
```

**Sync only reports and expenses:**

```yaml
source: EXPENSIFY
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: expensify.{stream_name}

streams:
  reports:
  expenses:
```

## Endpoints

### Policy Data

| Endpoint               | Description                                | Incremental |
| ---------------------- | ------------------------------------------ | ----------- |
| `policies`             | List of all accessible policies/workspaces | No          |
| `policy_categories`    | Expense categories for each policy         | No          |
| `policy_tags`          | Tags/labels for each policy                | No          |
| `policy_employees`     | Employees/members for each policy          | No          |
| `policy_report_fields` | Custom report fields for each policy       | No          |

### Expense Data

| Endpoint   | Description                                                                   | Incremental |
| ---------- | ----------------------------------------------------------------------------- | ----------- |
| `reports`  | Expense reports (all states: Open, Submitted, Approved, Reimbursed, Archived) | Yes         |
| `expenses` | Individual expense transactions within reports                                | Yes         |

To discover available endpoints:

```bash
sling conns discover EXPENSIFY
```

## Incremental Sync

The `reports` and `expenses` endpoints support incremental sync using date-based filtering:

* **First run:** Fetches all records from `anchor_date` (default: 1 year ago) to present
* **Subsequent runs:** Only fetches records modified after the last sync

The connector tracks:

* `last_approved` for reports (based on the `submitted` date)
* `last_modified` for expenses (based on the `modified` date)

## Rate Limiting

Expensify's Integration Server API has strict rate limits. The connector:

* Uses conservative rate limiting (\~1 request per 3 seconds)
* Limits concurrency to 1 request at a time
* Automatically retries with exponential backoff on 429 (rate limit) and 400 responses

{% hint style="info" %}
If you encounter rate limit errors, try running streams individually rather than all at once.
{% endhint %}

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/expensify.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.