Skip to main content
Expensify connects through its Integration Server API using a Partner User ID and Partner User Secret. An admin can choose one shared account or let each member connect an individual account.

Setup

  1. Open Control Hub > Integrations, find Expensify, and open its settings.
  2. Choose Individual accounts or Shared account.
  3. Choose Read reports and policies or Read and create expenses.
  4. For shared access, enter the account email and credentials from Expensify’s integrations page. For individual access, save the settings, then use Your connections > Expensify > Connect. Members can also connect directly from a chat using an agent with Expensify tools.
  5. Add the tools below to your agent and save it.
Credentials are checked by listing accessible policies before they are saved. This confirms policy access; it does not confirm permission to create expenses or verify that the entered email belongs to those credentials.
Expensify restricts the expense creation API’s employee email parameter to accounts with advanced permissions. An individual API credential does not automatically grant those permissions. If creation is denied, contact Expensify support to confirm or enable access for your account/domain.

Tools

Report and expense data

Report queries include every field in Expensify’s export template reference. Existing response fields remain available. Additional optional values are null when Expensify does not provide them, rather than being assumed false, zero, or populated because a policy requires them.
  • Reports: policy ID/name, account ID, created/submitted/approved/reimbursed dates, display status, reimbursement ID and ACH flag, legacy report ID, submitter/manager details, employee custom fields, all custom report fields, approvers, and history/comments.
  • Expenses: raw tag and tag GL code, numbered tag levels and GL codes, billable/reimbursable flags, category GL/payroll codes, bank/MCC, insertion timestamp, original and modified amounts/merchant/dates, converted amount and exchange rate, tax details, receipt metadata/URL, attendees, expense type, and distance/custom units.
tag is returned verbatim. tag_levels contains every available ntag1, ntag2, etc. and corresponding ntag1GlCode, etc.; it has no fixed number of levels. Use expensify_policies with fields: ["tags"] to interpret the policy’s ordered tag definitions. Do not assume the first tag always means Projects or infer named dimensions from a guessed delimiter. amount_cents retains the existing behavior: modified amount when present, otherwise original amount, in the expense’s currency. original_amount_cents and modified_amount_cents preserve both versions; converted_amount_cents, when provided, is in the report’s currency. Tax amounts are also in cents. Codes retain their leading zeros when supplied as strings. Top-level IDs are strings. Nested objects (custom_fields, receipt, units, attendees, approvers, action_list, submitter, manager) retain Expensify’s original nested field names. Large agent responses are written in full to a JSON file for execute_python; no expense fields are dropped to fit a preview. Direct API/app calls return the full payload up to the shared response-size limit and otherwise ask for a narrower query. The provider download remains bounded to 5 MB; reduce report IDs or the date range if that limit is reached. Report queries filter on the later of report creation or submission date, not the expense date. Date ranges must be no longer than 365 days. Unreported expenses are excluded. A result at the requested limit may be incomplete; narrow the dates or query specific IDs. Reads do not mark reports as exported or send emails. Expense creation accepts a positive integer amount in cents (1234 means 12.34) and an uppercase currency code. Individual mode fixes the destination to the account email entered when connecting. Shared mode can target another employee only when the shared credentials have the necessary Expensify permissions. The pilot does not upload receipts, submit or approve reports, or make payments.

Managing access

Individual credentials are scoped to the signed-in member and organization. A missing individual connection never falls back to shared credentials. An admin’s read-only setting blocks expense creation for both modes. Use Reconnect or Update credentials to replace credentials, or Disconnect to remove Aster’s saved copy. An admin removing the integration removes all saved personal Expensify credentials in that organization. Switching to shared mode removes personal credentials; switching to individual mode removes the shared credentials. Disconnecting Aster does not revoke the key in Expensify.

Troubleshooting

  • Credentials rejected: Confirm the Partner User ID and Partner User Secret, then reconnect. Your account must have Integration Server API access.
  • Creation denied: Ask Expensify support about advanced permissions for the expense creator API. A successful connection test verifies policy reads only.
  • Rate limit: Expensify allows 5 requests per 10 seconds and 20 per minute. A report query uses two requests: export and download. Wait before trying again.
  • Uncertain creation: A timeout or incomplete response may occur after the expense is created. Check Expensify before retrying. Aster does not automatically retry writes, and an external reference ID is not a deduplication guarantee.

OAuth and MCP

This version uses API credentials. Expensify’s Integration Server OAuth program requires partner onboarding. Its official MCP currently provides read-only tools, and the hosted Aster callback failed authorization in our launch testing. OAuth is a separate follow-up. See Expensify’s API documentation for provider permissions and limits.