Expensify

Expensify Integration Server credentials are separate from your regular Expensify login — they are special partner API credentials that you generate specifically for integration use. Log into Expensify with your admin account at expensify.com. Then navigate directly to: https://use.expensify.com/tools/integrations On the Integration Server page you will see two values: - partnerUserID — this is often in the format 'partner-XXXXXXXXXXXXXXXX' (a string starting with 'partner-', not your email address). This is the most common source of 'Invalid credentials' errors — builders assume it is their email, copy their email, and get a 400 error. It is not your email. - partnerUserSecret — a long random string, your API password Copy both values. Store them securely — you will add them to Bubble's API Connector as Private parameters. Also note your Expensify policy ID (policyIDList). Find this by going to your Expensify Workspace Settings — the policy ID appears in the URL when you are in the workspace settings page (format: A1B2C3D4E5F6G7H8). You will need this in the requestJobDescription for filtered report queries. If you do not see an Integration Server page, check that you are logged in as an admin user on a company Workspace (not a free personal account). The Integration Server is a business feature. Do NOT share these credentials with employees — they grant admin-level access to your Expensify policy data.

1// Credential types:
2// partnerUserID: 'partner-abc123def456ghi789' (NOT your email)
3// partnerUserSecret: 'longRandomSecretString123'
4// policyID: 'A1B2C3D4E5F6G7H8' (from Workspace Settings URL)
5
6// Where to find policyID:
7// Log into Expensify → click your Workspace name → Settings
8// URL format: https://www.expensify.com/admin_policies?param={"policyID":"A1B2C3D4E5F6G7H8"}
9// Or check Integration Server page — it may list accessible policies

Expensify's API uses application/x-www-form-urlencoded body format — the same format as a standard HTML form submission. This is NOT JSON. Configuring the wrong body type in Bubble's API Connector causes 400 errors even with correct credentials. Go to Plugins tab in your Bubble editor. If API Connector is not installed, click 'Add plugins', search for 'API Connector' (by Bubble), and install it. Click 'Add another API'. Name it 'Expensify'. Set the base URL to: https://integrations.expensify.com Do NOT add any shared headers for authentication — Expensify uses form body parameters for credentials, not HTTP headers. Add a call named 'Run Operation': - Method: POST - Path: /Integration-Server/ExpensifyIntegrations - Body type: Form (this is critical — must be Form, not JSON, not Raw) Add three form parameters: 1. Key: partnerUserID | Value: [partner_user_id] | Enable 'Private' checkbox 2. Key: partnerUserSecret | Value: [partner_user_secret] | Enable 'Private' checkbox 3. Key: requestJobDescription | Value: [request_job_description] | Do NOT mark Private (this value changes per operation and is constructed dynamically in Bubble) For the Initialize Call, you need real values. Temporarily enter your actual partnerUserID and partnerUserSecret as the parameter default values (you can clear them after initialization). For requestJobDescription, use this minimal test payload: {"type":"get","credentials":{},"inputSettings":{"type":"reports","filters":{"policyIDList":["YOUR_POLICY_ID"],"statusFilters":["Submitted","Approved"],"startDate":"2026-01-01"}}} Replace YOUR_POLICY_ID with your actual policy ID. Click 'Initialize call'. A successful response returns a JSON with a 'reports' array. Bubble detects the response fields automatically. IMPORTANT: after the Initialize Call succeeds, clear the hardcoded credential values from the parameter defaults — they should be passed dynamically from your Bubble database at call time, not hardcoded.

1// Bubble API Connector Configuration
2{
3  "api_name": "Expensify",
4  "base_url": "https://integrations.expensify.com",
5  "shared_headers": [],
6  "call": {
7    "name": "Run Operation",
8    "method": "POST",
9    "path": "/Integration-Server/ExpensifyIntegrations",
10    "body_type": "Form",
11    "form_parameters": [
12      { "key": "partnerUserID", "value": "[partner_user_id]", "private": true },
13      { "key": "partnerUserSecret", "value": "[partner_user_secret]", "private": true },
14      { "key": "requestJobDescription", "value": "[request_job_description]", "private": false }
15    ],
16    "use_as": "Action"
17  }
18}
19
20// Test requestJobDescription for Initialize Call:
21// {"type":"get","credentials":{},"inputSettings":{"type":"reports","filters":{"policyIDList":["YOUR_POLICY_ID"],"statusFilters":["Submitted"],"startDate":"2026-01-01"}}}

Now build the workflow that retrieves expense reports from Expensify and displays them in a Bubble Repeating Group. This uses the 'get' type requestJobDescription. The requestJobDescription for fetching reports is a JSON string that Bubble must construct dynamically. The cleanest approach is to define a text constant in Bubble using a 'Format as text' expression in the workflow. Add a button to your page: 'Load Expense Reports'. In the button's workflow: Step 1: Call API → Expensify > Run Operation For the requestJobDescription parameter, click the value field and select 'Create expression'. Build the JSON string using Bubble's text concatenation. Here is the JSON structure you need: {"type":"get","credentials":{},"inputSettings":{"type":"reports","filters":{"policyIDList":["POLICY_ID_HERE"],"statusFilters":["Submitted","Approved"],"startDate":"2026-01-01","endDate":"2026-03-31"}}} In Bubble, build this as a static text string with dynamic parts: - Replace the policyIDList value with a reference to your stored policyID - Replace startDate/endDate with formatted date expressions using 'Current date/time:formatted as text' with format YYYY-MM-DD For the partnerUserID and partnerUserSecret parameters, reference your stored credentials. Best practice: store them in an App Data record (a single 'ExpensifyConfig' record with partnerUserID and partnerUserSecret fields, both marked Private in Privacy Rules). Reference them as 'Search for ExpensifyConfig:first item's partnerUserID'. Step 2: Store results in Bubble's database. The API response contains a reports array. Use 'Make changes to a thing' in a loop — or better: store the raw response and parse it for display. Create an 'ExpensifyReport' data type in Bubble with fields: report_id (Text), employee_email (Text), total_amount (Number), status (Text), submitted_date (Date), report_name (Text). Create ExpensifyReport records from the API response data, setting each field from the corresponding response field. Step 3: Refresh your Repeating Group. Set the Repeating Group's data source to 'Search for ExpensifyReports' to display the stored data. Alternatively, for simpler use cases, set the Repeating Group to 'Get data from external API' → Expensify > Run Operation — this makes a live API call on every page load but avoids storing in the database.

1// requestJobDescription for fetching submitted reports:
2// (Pass as Text parameter to Run Operation call)
3{
4  "type": "get",
5  "credentials": {},
6  "inputSettings": {
7    "type": "reports",
8    "filters": {
9      "policyIDList": ["A1B2C3D4E5F6G7H8"],
10      "statusFilters": ["Submitted", "Approved"],
11      "startDate": "2026-01-01",
12      "endDate": "2026-03-31",
13      "reportIDList": []
14    }
15  }
16}
17
18// Response shape (partial):
19{
20  "reports": [
21    {
22      "reportID": "R12345678",
23      "managerEmail": "manager@company.com",
24      "accountEmail": "employee@company.com",
25      "total": 12750,
26      "currency": "USD",
27      "status": "SUBMITTED",
28      "submitted": "2026-01-15",
29      "reportName": "January Business Travel",
30      "expenses": []
31    }
32  ]
33}
34// Note: total = 12750 means $127.50 (amount in cents)

The 'create expense' operation uses the same single Expensify endpoint with a different requestJobDescription. The key concepts: amounts in cents, employeeEmail must match an Expensify account, and a policyIDList must be specified. Build an 'Add Expense' form on your Bubble page with fields: - Merchant name (Text input) - Amount (Number input — the user enters dollars/cents in decimal format) - Date (Date picker) - Category (Dropdown — populated from your Expensify policy's categories) - Business purpose (Text input) In the 'Submit Expense' button workflow: Step 1: Validate inputs — check that amount > 0, merchant is not empty, date is selected. Step 2: Call API → Expensify > Run Operation For requestJobDescription, build the following JSON string dynamically: {"type":"Expense","credentials":{},"inputSettings":{"type":"expenses","employeeEmail":"[current-user-email]","transactionList":[{"created":"[formatted-date]","currency":"USD","amount":[amount-in-cents],"merchant":"[merchant-name]","category":"[category]","comment":"[business-purpose]","transactionID":"[unique-id]"}]}} In Bubble's expression builder: - [current-user-email]: Current User's email - [formatted-date]: Date picker's value formatted as text with format YYYY-MM-DD - [amount-in-cents]: Amount input's value × 100 converted to a whole number (no decimals) - [merchant-name]: Merchant input's value - [category]: Category dropdown's value - [unique-id]: generate with a timestamp + random string (use Bubble's 'generate a random string' expression) Step 3: Show confirmation — display 'Expense submitted successfully!' when the API call returns a success response. Create an ExpenseSubmission record in Bubble's database with the submission details for your records. IMPORTANT: the transactionID field must be unique per expense — Expensify uses it for idempotency. If you submit the same transactionID twice, Expensify creates only one expense. Generate a unique ID per submission using timestamp + random string. Each employee submitting expenses through your Bubble app must have an Expensify account with the same email address as their Bubble account (Current User's email). If an employee's email does not exist in Expensify, the expense creation returns an error about invalid employee.

1// requestJobDescription for creating an expense:
2// (Build this as a dynamic Text parameter in Bubble)
3{
4  "type": "Expense",
5  "credentials": {},
6  "inputSettings": {
7    "type": "expenses",
8    "employeeEmail": "employee@company.com",
9    "transactionList": [
10      {
11        "created": "2026-01-09",
12        "currency": "USD",
13        "amount": 2550,
14        "merchant": "Starbucks",
15        "category": "Meals & Entertainment",
16        "comment": "Client coffee meeting with ABC Corp",
17        "transactionID": "bubble-20260109-143022-abc123",
18        "billable": false
19      }
20    ]
21  }
22}
23
24// CRITICAL: amount = cents, NOT dollars
25// $25.50 → amount: 2550
26// $125.00 → amount: 12500
27
28// In Bubble expression for amount:
29// Amount input's value * 100 :rounded to 0 decimal places

The approval operation uses the same single endpoint with 'type': 'update' and an actionList containing 'Approve'. This workflow should only be accessible to managers and should include a confirmation step before sending the approval. Add an 'Approve Report' button to your manager dashboard Repeating Group (visible only when the report status is 'Submitted' — use Bubble's Conditional to hide the button for already-approved reports). In the 'Approve Report' button's workflow: Step 1: Show a confirmation dialog — use Bubble's Alert element or a custom popup: 'Approve report [Report Name] from [Employee Email] for [Total Amount]? This action cannot be undone.' Step 2 (after confirmation): Call API → Expensify > Run Operation For requestJobDescription: {"type":"update","credentials":{},"inputSettings":{"type":"reports","filters":{"reportIDList":["[report_id]"]},"onReceive":{"actionList":["Approve"]}}} In Bubble's expression builder, replace [report_id] with the current Repeating Group cell's ExpensifyReport report_id field. Step 3: Update the local Bubble database — change the ExpensifyReport record's status field to 'Approved' and set an 'approved_by' field to Current User's email and 'approved_at' to Current date/time. Step 4: Refresh the Repeating Group to reflect the status change. For rejections, use the same structure with actionList: ['Reject'] — but note that Reject moves the report back to 'Open' state in Expensify, not 'Rejected'. You may want to add a rejection reason in Bubble's database for audit purposes, even if Expensify does not capture it natively. Security: add a Bubble workflow condition at the start — 'Only when: Current User's role = Manager'. This prevents non-managers from triggering the approval even if they somehow access the button. Also ensure your Privacy Rules restrict the manager dashboard page to manager-role users only.

1// requestJobDescription for approving a report:
2{
3  "type": "update",
4  "credentials": {},
5  "inputSettings": {
6    "type": "reports",
7    "filters": {
8      "reportIDList": ["R12345678"]
9    },
10    "onReceive": {
11      "actionList": ["Approve"]
12    }
13  }
14}
15
16// For rejection:
17{
18  "type": "update",
19  "credentials": {},
20  "inputSettings": {
21    "type": "reports",
22    "filters": {
23      "reportIDList": ["R12345678"]
24    },
25    "onReceive": {
26      "actionList": ["Reject"]
27    }
28  }
29}
30
31// Bubble workflow step after successful approval:
32// Make changes to ExpensifyReport (where report_id = R12345678):
33//   status = 'Approved'
34//   approved_by = Current User's email
35//   approved_at = Current date/time

Before going live, apply Bubble Privacy Rules to protect credential data and expense records, and implement consistent amount conversion throughout your app. Privacy Rules for ExpensifyConfig (your credentials store): Go to Data tab → Privacy → ExpensifyConfig. Add a rule: 'No one can view partnerUserID or partnerUserSecret'. Under 'All Users', uncheck View for both fields. This ensures credentials are only accessed programmatically by Backend Workflows and API calls — no user can read them through Bubble's Data API or the debug panel. Privacy Rules for ExpensifyReport: Add a rule: 'This ExpensifyReport's employee_email = Current User's email' → check View for all fields. This ensures employees only see their own expense reports. For managers, add a second rule: 'Current User's role = Manager AND Current User's managed_team contains this ExpensifyReport's employee_email' → check View for all fields. Amount conversion — implement it consistently in three places: 1. Creating expenses: multiply the user-entered dollar amount by 100 in Bubble's expression builder. Use: 'Amount input's value * 100 :rounded to 0 decimal places'. The rounded-to-zero-places removes any floating point artifacts. 2. Displaying report totals: divide the stored cent value by 100 for display. In your Repeating Group text element: 'ExpensifyReport's total_amount / 100 :formatted as number (2 decimal places)'. Prefix with your currency symbol. 3. Storing in Bubble's database: when you store the total from an Expensify response, you can store it in cents (as-is) or convert to dollars at storage time. Storing in cents avoids floating-point loss and matches Expensify's native format. Just ensure your display always divides by 100. WU economy: the Expensify API integration has low WU cost compared to other integrations — no token refresh, no polling loops, just direct API calls. The main cost driver is if you load expense reports on every page view for many concurrent managers. Cache the report list in Bubble's database and refresh on demand (a 'Refresh' button) rather than on every page load.

1// Privacy Rules for ExpensifyConfig type:
2// Add rule: All Users → uncheck View for: partnerUserID, partnerUserSecret
3// Purpose: credentials never exposed via Bubble Data API
4
5// Privacy Rules for ExpensifyReport type:
6// Rule 1: 'This ExpensifyReport's employee_email is Current User's email'
7//   → View: all fields (employees see own reports)
8// Rule 2: 'Current User's role is Manager'
9//   → View: all fields (managers see all reports under their policy)
10
11// Amount conversion examples:
12// User enters: $125.50
13// Stored / sent to Expensify: 12550 (cents)
14// (125.5 * 100 = 12550, rounded to 0 decimal places)
15
16// Display from Expensify response (total: 12550):
17// 12550 / 100 = 125.5 → formatted as '$125.50'
18
19// Dry-run mode for testing (add to any requestJobDescription):
20// { "type": "...", "dry-run": true, ... }
21// Validates request without creating real records