> Continuous Process Improvement > Expense Management > Expensify > Data Template

Your Expense Management Data Template

Expensify

Expense Management Attributes (21) Expense Management Activities (13) Extraction Guides (3)

Your Expense Management Data Template

This template provides a clear roadmap for collecting the necessary data to analyze your expense management process. It outlines the crucial attributes to gather, the key activities to track, and practical guidance for extracting this information from your Expensify system. Use this resource to prepare your data for powerful process mining insights.

Recommended attributes to collect for comprehensive analysis
Key activities to track for accurate process discovery
Practical guidance for data extraction

New to event logs? Learn how to create a process mining event log.

Download Template

Expense Management Attributes

These are the recommended data fields to include in your event log for comprehensive expense management analysis and optimization.

3 Required 5 Recommended 13 Optional

	Name	Description
	Activity Name ActivityName	The name of the business event that occurred at a specific point in time for an expense report.
Description The Activity Name describes a specific step or milestone in the expense management process, such as 'Expense Report Submitted' or 'Manager Approved'. It forms the backbone of the process map, allowing analysts to visualize the flow of work, identify common pathways, and spot deviations or bottlenecks. Analyzing the sequence of activities is fundamental to understanding process efficiency and compliance. Why it matters This attribute defines the steps in the process map, making it possible to visualize and analyze the process flow, variations, and rework loops. Where to get This attribute is typically derived by mapping report status changes, comments, or history log entries from Expensify to a standardized list of activities. Examples Expense Report SubmittedManager ApprovedFinance RejectedReimbursement Executed
	Event Time EventTime	The timestamp indicating when a specific activity or event occurred for an expense report.
Description Event Time provides the precise date and time for each activity in the process. This temporal information is essential for calculating cycle times, durations, and waiting times between different steps. It enables the analysis of bottlenecks, performance trends over time, and compliance with service level agreements. Without accurate timestamps, process mining analysis is limited to flow discovery. Why it matters Timestamps are essential for all time-based analysis, including calculating cycle times, identifying bottlenecks, and monitoring process performance. Where to get This is the creation timestamp associated with each history log entry or status change in the Expensify report data. Examples 2023-10-26T10:00:00Z2023-10-27T14:35:10Z2023-11-01T09:12:05Z
	Expense Report ID ExpenseReportId	The unique identifier for an expense report, grouping all related activities from submission to reimbursement.
Description The Expense Report ID is the primary case identifier for the expense management process. Each ID represents a single collection of expenses submitted by an employee for approval and reimbursement. This attribute is crucial for tracking the end-to-end journey of an expense report, allowing for the reconstruction of its entire lifecycle, including all submissions, approvals, rejections, and payments. Why it matters It allows for the aggregation of all related events into a single process instance, which is the foundation of any process mining analysis. Where to get This is the primary key in the expense reports data object, often available via the Expensify API reports endpoint as 'reportID'. Examples RPT_84321RPT_99012RPT_10573
	Approver Approver	The name or ID of the user responsible for approving or rejecting the expense report.
Description The Approver attribute identifies the manager or finance team member who takes action on a submitted expense report. This is essential for analyzing approver-specific behavior, such as approval times, rejection rates, and workload distribution. Understanding approver performance can help identify training needs, reallocate workloads, and streamline the approval process. Why it matters This attribute is key to analyzing approval bottlenecks, workload distribution, and approver-specific rejection rates. Where to get This information is found in the report's history or workflow log, often associated with approval or rejection events. The field may be labeled 'managerEmail' or similar. Examples jane.doe@example.comjohn.smith@example.comfinance.approver@example.com
	Employee Department EmployeeDepartment	The business department or unit to which the submitter belongs.
Description This attribute indicates the organizational department of the employee submitting the expense report, such as 'Sales', 'Engineering', or 'Marketing'. It is a crucial dimension for analysis, allowing for comparisons of cycle times, rejection rates, and policy compliance across different parts of the business. This helps identify department-specific issues or training needs. Why it matters Enables powerful drill-down analysis to compare process performance and compliance across different business units. Where to get This information might be stored as a tag on the report or associated with the submitter's user profile in Expensify. It may require enrichment from an external HR system. Examples SalesMarketingEngineeringFinance
	Policy Violation Flag PolicyViolationFlag	A boolean indicator that is true if the report has been flagged for a policy violation.
Description This flag indicates whether an expense report has triggered one or more policy violations, such as exceeding a spending limit or lacking a receipt. Expensify's automated system often flags these issues. This attribute is essential for the Policy Violation Overview dashboard, helping to quantify compliance issues and target areas for improvement. Why it matters Directly measures policy compliance and helps identify reports that require additional scrutiny, making it a key input for compliance dashboards. Where to get Expensify reports often contain a specific field or status indicating a violation, such as 'hasViolations' or a similar boolean flag. Examples truefalse
	Report Total Amount ReportTotalAmount	The total monetary value of the expense report.
Description This attribute represents the sum of all expenses included in a single expense report. It is a critical financial metric used for various analyses, such as identifying high-value expenses that may require additional scrutiny or follow a different approval path. It is also used in financial reporting and for understanding spending patterns across the organization. Why it matters Enables analysis of high-value expense reports, helps identify spending trends, and is crucial for financial and compliance dashboards. Where to get Available in the Expensify reports object, often named 'total' or 'amount'. Examples 150.752500.0089.50
	Submitter Submitter	The employee who created and submitted the expense report.
Description The Submitter attribute identifies the employee who incurred the expenses and is seeking reimbursement. This information is used to analyze expense patterns by employee, department, or role. It helps answer questions about which employees or groups experience the most delays or have the highest policy violation rates, contributing to a better employee experience analysis. Why it matters Allows for analysis of process performance from the employee's view, helping to identify groups with frequent issues or delays. Where to get This is a primary field on the expense report object, typically labeled 'policyEmail', 'submitterEmail', or 'employeeEmail'. Examples sara.jones@example.comkevin.lee@example.commaria.garcia@example.com
	Audit Outcome AuditOutcome	The result of a manual or automated audit performed on the expense report.
Description This attribute captures the outcome of an audit, which might be 'Passed', 'Failed', or 'Passed with Findings'. This is relevant for companies that have a formal audit step in their expense process, either for all reports or a sample. Analyzing audit outcomes helps in understanding compliance levels and the effectiveness of existing controls. Why it matters Directly measures the outcome of compliance checks and is essential for analyzing the effectiveness of the audit process. Where to get This is likely a conceptual attribute or might be stored as a tag or in a comment. Its existence depends on the company's specific process configuration within Expensify. Examples PassedFailed - Policy ViolationPassed with Remarks
	Currency Currency	The currency code for the amounts in the expense report.
Description The Currency attribute specifies the currency of the Report Total Amount, such as USD, EUR, or GBP. This is crucial for organizations that operate in multiple countries to ensure that financial data is interpreted correctly. All monetary values should be analyzed in conjunction with this attribute to avoid incorrect aggregations. Why it matters Ensures accurate financial analysis and reporting by providing the necessary context for all monetary values. Where to get This is a standard field in the Expensify report object, often called 'currency'. Examples USDEURGBPCAD
	Event End Time EventEndTime	The timestamp when a specific activity ended. Useful for activities with a measurable duration.
Description While many activities in expense management are instantaneous, some like 'Manager Review' can be modeled with a start and end time. The Event End Time marks the completion of such an activity. It is used in conjunction with the Start Time to calculate the precise processing time for individual steps, providing a more detailed view of where time is spent. Why it matters Allows for the calculation of activity processing times, which helps differentiate between active work time and idle waiting time. Where to get This is typically not a direct field. It is derived by taking the timestamp of the next event in the sequence for the same case. Examples 2023-10-26T10:05:12Z2023-10-27T15:00:00Z
	Expense Category ExpenseCategory	The category assigned to an individual expense line item within a report.
Description Expense Category classifies the type of spending, such as 'Travel', 'Meals & Entertainment', or 'Software'. While a report can have multiple categories, this attribute is often denormalized to the report level, for example by taking the most frequent category or the category with the highest amount. It is used to analyze spending trends and to check policy compliance for specific types of expenses. Why it matters Helps in analyzing spending patterns, policy violations, and approval times for different types of expenses. Where to get Found at the line-item level ('transactions') within a report. An aggregation or business rule is needed to assign it to the case level. Examples AirfareLodgingMealsOffice Supplies
	Is First Pass Approval IsFirstPassApproval	A calculated flag that is true if the report was approved without any rejections or revisions.
Description This boolean flag is calculated for each expense report to determine if it went through the approval process without any negative outcomes, such as being rejected or sent back for revision. It is a direct measure of process quality and efficiency, feeding directly into the First-Pass Approval Rate KPI. A high rate indicates that submissions are of good quality and policies are well understood. Why it matters Directly measures the quality of initial submissions and the efficiency of the approval flow, highlighting the frequency of rework. Where to get This is calculated by checking the sequence of activities for a given ExpenseReportId. If the sequence does not contain 'Manager Rejected', 'Finance Rejected', or 'Report Sent Back For Revision', the flag is true. Examples truefalse
	Last Data Update LastDataUpdate	The timestamp indicating when the data for this record was last refreshed from the source system.
Description This attribute records the date and time the data was last extracted and updated in the process mining tool. It provides transparency on data freshness and is crucial for understanding how current the analysis is. This helps users trust the insights and make informed decisions based on timely data. Why it matters Ensures users are aware of the data's freshness, which is critical for the relevance and accuracy of the process analysis. Where to get This is typically the timestamp of the data extraction job, added during the data transformation (ETL) process. Examples 2023-11-20T08:00:00Z2023-11-21T08:00:00Z
	Payment Method PaymentMethod	The method used for reimbursing the employee.
Description This attribute describes how the employee was reimbursed, such as 'Direct Deposit (ACH)', 'PayPal', or 'Company Credit Card'. Analyzing the payment method can help in understanding the reimbursement part of the process, especially if certain methods are associated with longer delays. It provides additional context for the final steps of the process. Why it matters Provides context for the reimbursement phase and can be used to analyze delays or costs associated with different payout methods. Where to get This information is typically available within the reimbursement details of a closed report. Examples ACHPayPalBill.com
	Policy Name PolicyName	The name of the expense policy applied to the report.
Description In Expensify, different groups of employees can be subject to different expense policies. This attribute identifies the specific policy that governs the rules for the expense report. It is a critical dimension for analysis, as it allows for comparing compliance and efficiency across different policies, which may have different rules and approval workflows. Why it matters Allows for segmenting the process analysis by the set of rules applied, which is essential for understanding variations driven by different policies. Where to get This is a standard field on the report object in Expensify, often named 'policyID' or 'policyName'. Examples US Employee PolicyUK Sales Team PolicyExecutive Travel Policy
	Processing Time ProcessingTime	The duration of time spent on a single activity.
Description Processing Time is a calculated metric that measures the time between an activity's start and end time. It represents the active time spent on a task. For example, it could measure how long a manager had a report open before approving it. This metric is used to distinguish between active work time and waiting time, providing deeper insight into process efficiency. Why it matters Helps distinguish between active processing time and passive waiting time, allowing for more precise identification of bottlenecks. Where to get This is calculated during data transformation by subtracting the EventTime from the EventEndTime. Examples 864003600600
	Rejection Reason RejectionReason	The reason provided by an approver when rejecting an expense report or sending it back for revision.
Description When an expense report is rejected, the approver can typically provide a reason. This text attribute captures that reason, providing invaluable qualitative insight into why reports fail approval. Analyzing rejection reasons helps identify common submission errors, unclear policies, or areas where employees need more training, directly supporting efforts to improve the first-pass approval rate. Why it matters Provides qualitative data that explains why rework occurs, which is crucial for root cause analysis of report rejections. Where to get This information is usually found in the comments or history log associated with a rejection event. Examples Missing receipt for item over $75Incorrect expense category selectedDuplicate expense submitted
	Report Status ReportStatus	The current state of the expense report in its lifecycle.
Description The Report Status indicates the current position of the expense report in the process, such as 'OPEN', 'SUBMITTED', 'APPROVED', 'REIMBURSED', or 'CLOSED'. It provides a snapshot of the report's progress. In process mining, this attribute is often used to derive the Activity Name, but it can also be used as a dimension to analyze how much time reports spend in each state. Why it matters Indicates the current state of a case and is often the source for deriving the activity log for process mining. Where to get This is a standard field in the Expensify report object, often named 'status' or 'state'. Examples SUBMITTEDAPPROVEDREIMBURSEDCLOSED
	Source System SourceSystem	The system from which the data was extracted.
Description This attribute identifies the origin of the process data, which is 'Expensify' in this case. It is important for data governance, especially in environments where data from multiple systems is combined. It helps in tracing data lineage and understanding the context of the process. Why it matters Provides crucial context for data lineage and helps differentiate processes when data from multiple source systems is loaded into the same environment. Where to get This is a static value ('Expensify') that should be added during the data transformation process. Examples ExpensifyExpensifyAPI-v2.0
	Total Cycle Time TotalCycleTime	The total time elapsed from the creation of the first event to the completion of the last event for an expense report.
Description Total Cycle Time is a case-level calculation that measures the end-to-end duration of the expense management process for a single report. It is a key performance indicator (KPI) for overall process efficiency. This metric is calculated by taking the difference between the timestamp of the very first activity (e.g., 'Expense Report Created') and the very last activity (e.g., 'Reimbursement Executed'). Why it matters This is a primary KPI for measuring overall process velocity and identifying long-running cases that may indicate systemic issues. Where to get This attribute is calculated by taking (MAX(EventTime) - MIN(EventTime)) for each ExpenseReportId. Examples 6048001209600259200

Required Recommended Optional

Expense Management Activities

These are the key process steps and milestones to capture in your event log for accurate process discovery and bottleneck identification.

7 Recommended 6 Optional

	Activity	Description
	Expense Report Created	Marks the initiation of a new expense report by an employee. This is typically captured as an explicit event with a creation timestamp when the report is first saved in Expensify.
Why it matters This activity is the starting point for all process analysis and is crucial for measuring the total cycle time from creation to reimbursement. Where to get This event is captured from the report creation timestamp in Expensify's report history or audit logs. Every report object has a creation date. Capture Logged upon initial creation and saving of the expense report. Event type explicit
	Expense Report Submitted	The employee officially submits the completed expense report for the approval workflow to begin. This is a key transition from data entry to the review process, usually captured by a status change and a submission timestamp.
Why it matters This activity is a critical milestone that triggers the approval cycle. It serves as the starting point for measuring manager and finance review times. Where to get Inferred from the report's status changing from 'Open' or 'Draft' to 'Processing' or 'Submitted', along with the associated timestamp for this change. Capture Derived from the status change to 'Processing' and the associated submission timestamp. Event type inferred
	Finance Approved	The finance department or final approver has reviewed and given final approval for the expense report. This action is logged in the workflow history and typically changes the report status to 'Approved'.
Why it matters This is the final approval gate before reimbursement. The time taken for this step is critical for the overall cycle time and Average Reimbursement Lead Time KPI. Where to get Captured from the report's history or audit trail, which logs the final approval action, the approver from the finance team, and the timestamp. Capture Logged as a distinct final approval action in the report's workflow history. Event type explicit
	Manager Approved	The direct manager or first-level approver has reviewed and approved the expense report. This event is captured from the approval workflow log, which records the approver's action and timestamp.
Why it matters A critical milestone in the approval process. Analyzing the time from submission to this event helps identify manager related bottlenecks and measures the Manager Approval Cycle Time KPI. Where to get Captured from the report's history or audit trail, which explicitly logs the approval action, the approver's name, and the timestamp. Capture Logged as a distinct approval action in the report's workflow history. Event type explicit
	Reimbursement Executed	The payment has been successfully sent to the employee, completing the reimbursement part of the process. This is captured from payment processing logs or a final status update in Expensify.
Why it matters This is a key end-point for measuring employee facing cycle times. It is critical for the Average Expense Report Cycle Time and Average Reimbursement Lead Time KPIs. Where to get Inferred from the report status changing to 'Reimbursed'. Expensify's integration with payment systems provides a timestamp for this status change. Capture Derived from the report status changing to 'Reimbursed' and its associated timestamp. Event type inferred
	Report Closed	The expense report is formally closed in the system after all actions, including reimbursement and accounting sync, are complete. This event is typically inferred from a final, terminal status like 'Closed'.
Why it matters Provides a definitive end point for the process, distinct from reimbursement, which is useful for analyzing the final accounting and archival steps. Where to get Inferred from the report status changing to a terminal state like 'Closed'. This often happens after reimbursement and accounting export. Capture Derived from the report status changing to 'Closed' with its associated timestamp. Event type inferred
	Report Sent Back For Revision	An approver, either a manager or from finance, returns the report to the employee for correction or more information. This is typically inferred from a status change to 'Open' after it was 'Processing'.
Why it matters This activity represents rework, which is a major source of inefficiency. Tracking it helps quantify rework loops, measure the Rework Rate KPI, and identify root causes. Where to get Inferred from a report status change from 'Processing' or 'Submitted' back to 'Open'. The timestamp of this status change marks the event. Capture Derived from a report status change from 'Processing' back to 'Open'. Event type inferred
	Accounting Posted	The financial data from the expense report has been exported and posted to the company's accounting system or ERP. This is the final step, marking the process complete from a financial records perspective.
Why it matters Represents the final closure of the expense report in the financial system. It is important for measuring the full end to end process and ensuring data synchronization. Where to get Captured from integration logs between Expensify and the accounting software. This may require combining data from two systems. Capture Logged in the integration history when data is successfully synced to the accounting system. Event type explicit
	Expense Added To Report	Represents an employee adding a specific line item, such as a scanned receipt or a manually entered expense, to the report. This is captured as an entry in the report's detailed history log.
Why it matters Analyzing the time between report creation and when expenses are added can reveal delays in evidence gathering or submission preparation by employees. Where to get From the audit trail or history of the expense report, which logs actions like adding individual expense entries. Capture Logged in the report's history each time a new expense line is added. Event type explicit
	Finance Rejected	The finance department has reviewed and rejected the expense report, stopping the reimbursement process. This event is logged in the workflow history with a timestamp and rejection reason.
Why it matters Identifies bottlenecks and reasons for failure at the final review stage. It is essential for analyzing the overall rejection rate and compliance issues. Where to get Captured from the report's history, which records the rejection action by the finance team, along with a timestamp and user. Capture Logged as a distinct rejection action in the report's workflow history. Event type explicit
	Manager Rejected	The first-level approver has reviewed the expense report and rejected it, which typically stops the process. This is recorded as a rejection event in the workflow log, often with a reason provided.
Why it matters Analyzing rejection events is key to understanding the Expense Report Rejection Rate KPI. It helps identify common reasons for failure and areas needing process improvement. Where to get Captured from the report's history, which logs the rejection action, the rejector's identity, and the timestamp. The report status typically changes to 'Rejected'. Capture Logged as a distinct rejection action in the report's workflow history. Event type explicit
	Policy Violation Flagged	An automated check identifies an expense that violates company policy, such as being over budget or missing a receipt. This event is captured when a specific policy violation flag is set on the report or a line item.
Why it matters Highlights compliance issues and helps identify which policies are frequently violated, enabling targeted training or policy clarification. This is crucial for the Policy Violation Count KPI. Where to get Inferred from the 'Policy Violation' flag or attribute being set to true in the expense report data. The timestamp corresponds to when this flag was set. Capture Derived from the timestamp when the policy violation attribute for the report is updated. Event type inferred
	Reimbursement Scheduled	After final approval, the expense report is queued for payment processing. This event marks the transition from approval to the payment phase and is often captured when the report status changes to 'Reimbursing'.
Why it matters Marks the start of the reimbursement lead time. Analyzing the duration between this and the actual payment helps identify delays in the payout process. Where to get Inferred from a report status change to 'Reimbursing' or 'Processing Payment', with its associated timestamp. Capture Derived from a status change indicating the report is queued for payment. Event type inferred

Recommended Optional

Extraction Guides

How to get your data from Expensify

Steps

Log in to your Expensify account with Domain Admin or Policy Admin permissions.
Navigate to the Settings section, then go to Policies and select the specific group policy for which you want to export data.
In the left-hand menu, select the Export Formats option under the Reports category.
Click Add a new export format to begin creating the custom template. Name the template something descriptive, for example, ProcessMind Event Log Export.
In the export template editor, select the Reports export type. You will now define the columns for your CSV file. Use the Add a new column button to add each required field.
Configure the columns by entering the exact formulas provided in the query section below. This includes columns for the case ID, timestamps for each activity, and all required and recommended attributes.
After adding all the necessary columns, click Save to create the export template.
Navigate to the Reports page from the main Expensify menu. Use the filters to select the reports you want to analyze. It is crucial to set a specific date range, for instance, the last 3 to 6 months, to ensure a manageable file size.
Click the Export To button and select your newly created template, ProcessMind Event Log Export, from the dropdown list.
Expensify will generate the CSV file and send you a link to download it. Download the file to your local machine. The exported file will be in a "wide" format, with one row per expense report and separate columns for each activity's timestamp.
Transform the downloaded data from a wide format to a long format suitable for process mining. You can use tools like Microsoft Excel (with Power Query's Unpivot Columns feature), Python (with the pandas library), or other data preparation tools. The goal is to have one row per activity, with columns for ExpenseReportId, ActivityName, and EventTime.
Save the transformed data as a CSV file and upload it to the ProcessMind application.

Configuration

Admin Permissions: You must have Domain Admin or Policy Admin permissions for the relevant policy to create and manage export formats.
Export Template: A custom export template must be configured. This method will not work with the default templates.
Date Range: It is highly recommended to filter the export by a specific date range, such as 3-6 months, to keep the export process timely and the resulting file size manageable. Use the Submitted Date as the primary filter.
Report Status Filter: To capture the entire process lifecycle, avoid filtering by report status. Export all reports within the date range, including Open, Processing, Approved, Reimbursed, and Closed statuses.
Custom Fields: Attributes like EmployeeDepartment rely on your organization's specific Expensify configuration. If you use Tags or Report Fields for this information, you must add the corresponding formula, for example {report:tag:Department}, to the export template.

a Sample Query config

/*
This is not a script, but a configuration for the Expensify custom export template.
In the export format editor, create a new column for each line below, using the text on the right as the formula.
*/

// Case ID and Required Attributes
ExpenseReportId: {report:id}
EventTime_Created: {report:created}
EventTime_Submitted: {report:submitted}
EventTime_Approved: {report:approved}
EventTime_Reimbursed: {report:reimbursed}
EventTime_Closed: {report:closed}

// Recommended Attributes
ReportTotalAmount: {report:total}
Submitter: {report:submitter:email}
Approver: {report:approverEmail}
EmployeeDepartment: {report:tag:[Your Department Tag Name]}
PolicyViolationFlag: {report:hasViolations}

// --- Transformation Logic Overview ---
/*
After exporting the CSV with the columns above, you must unpivot the timestamp columns.
1. Load the CSV into a data transformation tool (e.g., Excel Power Query, Python pandas).
2. Select all the timestamp columns (EventTime_Created, EventTime_Submitted, etc.).
3. Use the "Unpivot" function. This will create two new columns: one containing the original column names (e.g., 'EventTime_Created') and another with the timestamp values.
4. Rename the column with the names to `ActivityName` and the column with values to `EventTime`.
5. Clean up the `ActivityName` column by removing the 'EventTime_' prefix to get clean activity names like 'Expense Report Created', 'Expense Report Submitted', etc.
6. For activities that do not have a direct timestamp export (e.g., 'Manager Approved', 'Reimbursement Scheduled'), you can duplicate an existing timestamp column (like 'EventTime_Approved') in your export template and rename it accordingly (e.g., `EventTime_ManagerApproved`). This uses the same timestamp as a proxy for multiple events, which should be noted during analysis.
*/

Steps

Prerequisites and Setup: Ensure you have Python 3 installed on your system. Install the necessary requests library by running pip install requests in your terminal or command prompt. You will also need API credentials from Expensify.
Obtain Expensify API Credentials: Log in to your Expensify account with administrator privileges. Navigate to Settings > Account > Integrations > Public API. Here you can generate your partnerUserID and partnerUserSecret. Securely store these credentials as they provide access to your company's data.
Configure Expensify Export Template: The script relies on a custom data export. In Expensify, go to Settings > Policies > [Your Group Policy] > Export Formats. Create a new export template that includes all necessary columns. Crucially, you must include fields such as Report ID, Created Date, Submitted Date, Approved Date, Reimbursed Date, Closed Date, Total Amount, Submitter Email, Approver Details, Policy Violations, and the detailed Report History Log. The Report History is essential for capturing events like rejections and comments.
Customize the Python Script: Copy the provided Python script into a file, for example, extract_expensify_log.py. Replace the placeholder values for PARTNER_USER_ID, PARTNER_USER_SECRET, START_DATE, END_DATE, and EXPORT_TEMPLATE_NAME with your specific credentials, desired date range, and the exact name of the export template you configured in the previous step.
Execute the Script to Download Data: Run the script from your terminal using python extract_expensify_log.py. The script will first authenticate with the Expensify API, then submit a job request to export the report data. It will poll the API every few seconds to check if the export is ready.
Wait for File Download: Once the export job is complete, the script will automatically download the resulting CSV file and save it as expensify_raw_export.csv in the same directory.
Transform Raw Data into Event Log: The script proceeds to read the downloaded expensify_raw_export.csv. It iterates through each row, which represents a single expense report, and unnests the data. For each relevant date column and history log entry, it creates a distinct row in the event log, corresponding to a business activity.
Generate Final Event Log File: After processing all the reports from the raw export, the script writes the transformed data into a new file named expensify_event_log.csv. This file is structured with the required columns: ExpenseReportId, ActivityName, EventTime, and other recommended attributes.
Prepare for ProcessMind Upload: Open the final expensify_event_log.csv file. Verify that the column headers match the requirements and that the data format is correct. The file is now ready to be uploaded to ProcessMind for analysis.

Configuration

API Credentials: A valid partnerUserID and partnerUserSecret from Expensify are required for authentication. The user associated with these credentials must have permissions to access and export report data.
Expensify Export Template: This is the most critical configuration. The entire extraction depends on a custom export template created in the Expensify UI. This template must contain all fields needed to derive the activities and attributes, especially the detailed Report History log, which contains timestamps and comments for approvals, rejections, and other workflow steps.
Date Range Filters: The script includes START_DATE and END_DATE variables. It is recommended to start with a smaller range, such as 3-6 months of data, to ensure the process works correctly before attempting to extract larger datasets.
Report Status Filter: The API request in the script can be modified to include a reportState filter (e.g., APPROVED, REIMBURSED, CLOSED) to narrow down the scope of the export. This can be useful for managing data volume or focusing on completed processes.
Python Environment: The script requires a Python 3 environment with the requests library installed. No other special libraries are needed, making the setup relatively straightforward.

a Sample Query python

import requests
import json
import time
import csv
from datetime import datetime

class=class="hl-string">"hl-comment"># --- PLACEHOLDERS: Replace with your actual credentials and settings ---
PARTNER_USER_ID = class="hl-string">'[Your Expensify Partner User ID]'
PARTNER_USER_SECRET = class="hl-string">'[Your Expensify Partner User Secret]'

class=class="hl-string">"hl-comment"># --- CONFIGURATION: Define the export parameters ---
class=class="hl-string">"hl-comment"># Use YYYY-MM-DD format for dates
START_DATE = class="hl-string">'2023-01-01'
END_DATE = class="hl-string">'2023-06-30'
class=class="hl-string">"hl-comment"># The exact name of the custom export format you created in Expensify
EXPORT_TEMPLATE_NAME = class="hl-string">'[Your Custom Report Export Template Name]'

API_URL = class="hl-string">'https://integrations.expensify.com/Integration-Server/Doc/v1.0/'
RAW_EXPORT_FILE = class="hl-string">'expensify_raw_export.csv'
EVENT_LOG_FILE = class="hl-string">'expensify_event_log.csv'

def execute_api_job(job_description):
    class="hl-string">"""Submits a job to the Expensify API and returns the response."""
    auth_payload = {
        class="hl-string">'partnerUserID': PARTNER_USER_ID,
        class="hl-string">'partnerUserSecret': PARTNER_USER_SECRET
    }
    data = {
        class="hl-string">'requestJobDescription': json.dumps(job_description),
        class="hl-string">'credentials': json.dumps(auth_payload)
    }
    response = requests.post(API_URL, data=data)
    response.raise_for_status() class=class="hl-string">"hl-comment"># Raises an exception for bad status codes
    return response.json()

class=class="hl-string">"hl-comment"># 1. Trigger the report export job
print(class="hl-string">'Requesting report export from Expensify...')
export_job_desc = {
    class="hl-string">'type': class="hl-string">'exportReport',
    class="hl-string">'credentials': {
        class="hl-string">'partnerUserID': PARTNER_USER_ID,
        class="hl-string">'partnerUserSecret': PARTNER_USER_SECRET
    },
    class="hl-string">'onReceive': {
        class="hl-string">'immediateResponse': [class="hl-string">'returnRandomFileName']
    },
    class="hl-string">'inputSettings': {
        class="hl-string">'type': class="hl-string">'report',
        class="hl-string">'filters': {
            class="hl-string">'startDate': START_DATE,
            class="hl-string">'endDate': END_DATE,
            class="hl-string">'markedAsExported': class="hl-string">'Expensify Export'
        }
    },
    class="hl-string">'outputSettings': {
        class="hl-string">'fileExtension': class="hl-string">'csv',
        class="hl-string">'fileBasename': EXPORT_TEMPLATE_NAME
    }
}

class=class="hl-string">"hl-comment"># The template is passed as a separate parameter for this job type
export_job_desc[class="hl-string">'template'] = fclass="hl-string">'<![CDATA[{EXPORT_TEMPLATE_NAME}]]>'

initial_response = execute_api_job(export_job_desc)
file_name = initial_response.get(class="hl-string">'fileName')

if not file_name:
    raise Exception(fclass="hl-string">'Failed to initiate export. Response: {initial_response}')

print(fclass="hl-string">'Export job started. Waiting for file: {file_name}')

class=class="hl-string">"hl-comment"># 2. Poll for the file until it's ready
while True:
    download_job_desc = {
        class="hl-string">'type': class="hl-string">'download',
        class="hl-string">'credentials': {
            class="hl-string">'partnerUserID': PARTNER_USER_ID,
            class="hl-string">'partnerUserSecret': PARTNER_USER_SECRET
        },
        class="hl-string">'fileName': file_name
    }
    download_response = execute_api_job(download_job_desc)
    if download_response.get(class="hl-string">'responseCode') == 200:
        print(class="hl-string">'File is ready for download.')
        with open(RAW_EXPORT_FILE, class="hl-string">'w', encoding=class="hl-string">'utf-8') as f:
            f.write(download_response[class="hl-string">'fileContents'])
        break
    elif download_response.get(class="hl-string">'responseCode') == 404:
        print(class="hl-string">'File not ready yet, waiting 10 seconds...')
        time.sleep(10)
    else:
        raise Exception(fclass="hl-string">'Failed to download file. Response: {download_response}')

class=class="hl-string">"hl-comment"># 3. Transform the raw export into an event log
print(fclass="hl-string">'Successfully downloaded raw data to {RAW_EXPORT_FILE}. Transforming to event log...')
event_log = []

with open(RAW_EXPORT_FILE, class="hl-string">'r', encoding=class="hl-string">'utf-8') as infile:
    reader = csv.DictReader(infile)
    for row in reader:
        class=class="hl-string">"hl-comment"># Standard report attributes
        report_id = row.get(class="hl-string">'Report ID')
        report_total = row.get(class="hl-string">'Total')
        submitter = row.get(class="hl-string">'Submitter Email')
        department = row.get(class="hl-string">'Submitter Department') class=class="hl-string">"hl-comment"># Assuming this is in your template
        
        class=class="hl-string">"hl-comment"># Helper to create event rows
        def add_event(activity_name, event_time_str, approver=None, violation=None):
            if event_time_str:
                event_log.append({
                    class="hl-string">'ExpenseReportId': report_id,
                    class="hl-string">'ActivityName': activity_name,
                    class="hl-string">'EventTime': event_time_str,
                    class="hl-string">'ReportTotalAmount': report_total,
                    class="hl-string">'Submitter': submitter,
                    class="hl-string">'EmployeeDepartment': department,
                    class="hl-string">'Approver': approver,
                    class="hl-string">'PolicyViolationFlag': violation
                })
        
        class=class="hl-string">"hl-comment"># Activity: Expense Report Created
        add_event(class="hl-string">'Expense Report Created', row.get(class="hl-string">'Created'))

        class=class="hl-string">"hl-comment"># Activity: Expense Report Submitted
        add_event(class="hl-string">'Expense Report Submitted', row.get(class="hl-string">'Submitted'))
        
        class=class="hl-string">"hl-comment"># Activity: Manager Approved / Finance Approved
        class=class="hl-string">"hl-comment"># Assumes approver details are in a single column like class="hl-string">'Approver 1: name@co.com (YYYY-MM-DD), Approver 2: ...'
        class=class="hl-string">"hl-comment"># This logic needs to be adapted to your specific export format.
        approvers_str = row.get(class="hl-string">'Approver History', class="hl-string">'') 
        if class="hl-string">'Manager' in approvers_str: class=class="hl-string">"hl-comment"># Example logic
             class=class="hl-string">"hl-comment"># Complex parsing might be needed here based on your template's format
             add_event(class="hl-string">'Manager Approved', row.get(class="hl-string">'Approved')) class=class="hl-string">"hl-comment"># Simplified, assumes class="hl-string">'Approved' date is manager's

        if class="hl-string">'Finance' in approvers_str: class=class="hl-string">"hl-comment"># Example logic
             add_event(class="hl-string">'Finance Approved', row.get(class="hl-string">'Final Approved')) class=class="hl-string">"hl-comment"># Assumes a separate column for final approval
        else:
             class=class="hl-string">"hl-comment"># Fallback if only one approval date exists
             add_event(class="hl-string">'Finance Approved', row.get(class="hl-string">'Approved'))

        class=class="hl-string">"hl-comment"># Activity: Reimbursement Scheduled
        add_event(class="hl-string">'Reimbursement Scheduled', row.get(class="hl-string">'Reimbursing Start Date')) class=class="hl-string">"hl-comment"># Assumes this column exists

        class=class="hl-string">"hl-comment"># Activity: Reimbursement Executed
        add_event(class="hl-string">'Reimbursement Executed', row.get(class="hl-string">'Reimbursed'))
        
        class=class="hl-string">"hl-comment"># Activity: Report Closed
        add_event(class="hl-string">'Report Closed', row.get(class="hl-string">'Closed'))
        
        class=class="hl-string">"hl-comment"># Activities from Report History Log
        class=class="hl-string">"hl-comment"># This is CRITICAL. Your export template must include the detailed history.
        class=class="hl-string">"hl-comment"># The history is often a multi-line text block in a single CSV cell.
        history_log = row.get(class="hl-string">'Report History', class="hl-string">'')
        for line in history_log.split(class="hl-string">'\n'): class=class="hl-string">"hl-comment"># Assuming newline separated history
            line_lower = line.lower()
            class=class="hl-string">"hl-comment"># Try to extract a timestamp from the history line
            try:
                class=class="hl-string">"hl-comment"># Expensify history format is often like class="hl-string">'MMM DD: ...'
                class=class="hl-string">"hl-comment"># This parsing logic is an example and MUST be adjusted to your format
                timestamp_str = line.split(class="hl-string">':')[0]
                class=class="hl-string">"hl-comment"># A real implementation needs more robust date parsing
                event_time = datetime.now().strftime(class="hl-string">'%Y-%m-%d %H:%M:%S') class=class="hl-string">"hl-comment"># Placeholder for parsed time
            except:
                continue

            if class="hl-string">'added expense' in line_lower:
                add_event(class="hl-string">'Expense Added To Report', event_time)
            elif class="hl-string">'violation' in line_lower:
                add_event(class="hl-string">'Policy Violation Flagged', event_time, violation=True)
            elif class="hl-string">'rejected' in line_lower and class="hl-string">'manager' in line_lower:
                add_event(class="hl-string">'Manager Rejected', event_time)
            elif class="hl-string">'rejected' in line_lower and class="hl-string">'finance' in line_lower: class=class="hl-string">"hl-comment"># Example keyword
                add_event(class="hl-string">'Finance Rejected', event_time)
            elif class="hl-string">'unapproved' in line_lower or class="hl-string">'sent back' in line_lower:
                add_event(class="hl-string">'Report Sent Back For Revision', event_time)
            elif class="hl-string">'exported to' in line_lower or class="hl-string">'posting' in line_lower:
                 add_event(class="hl-string">'Accounting Posted', event_time)

class=class="hl-string">"hl-comment"># 4. Write the final event log file
if event_log:
    with open(EVENT_LOG_FILE, class="hl-string">'w', newline=class="hl-string">'', encoding=class="hl-string">'utf-8') as outfile:
        fieldnames = [class="hl-string">'ExpenseReportId', class="hl-string">'ActivityName', class="hl-string">'EventTime', class="hl-string">'ReportTotalAmount', class="hl-string">'Submitter', class="hl-string">'EmployeeDepartment', class="hl-string">'Approver', class="hl-string">'PolicyViolationFlag']
        writer = csv.DictWriter(outfile, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(event_log)
    print(fclass="hl-string">'Event log successfully created at {EVENT_LOG_FILE}')
else:
    print(class="hl-string">'No events were generated. Check the raw export file and script logic.')

Steps

Log in to your Expensify account with Domain Admin or Policy Admin permissions.
Navigate to the Settings section, then go to Policies and select the specific group policy for which you want to export data.
In the left-hand menu, select the Export Formats option under the Reports category.
Click Add a new export format to begin creating the custom template. Name the template something descriptive, for example, ProcessMind Event Log Export.
In the export template editor, select the Reports export type. You will now define the columns for your CSV file. Use the Add a new column button to add each required field.
Configure the columns by entering the exact formulas provided in the query section below. This includes columns for the case ID, timestamps for each activity, and all required and recommended attributes.
After adding all the necessary columns, click Save to create the export template.
Navigate to the Reports page from the main Expensify menu. Use the filters to select the reports you want to analyze. It is crucial to set a specific date range, for instance, the last 3 to 6 months, to ensure a manageable file size.
Click the Export To button and select your newly created template, ProcessMind Event Log Export, from the dropdown list.
Expensify will generate the CSV file and send you a link to download it. Download the file to your local machine. The exported file will be in a "wide" format, with one row per expense report and separate columns for each activity's timestamp.
Transform the downloaded data from a wide format to a long format suitable for process mining. You can use tools like Microsoft Excel (with Power Query's Unpivot Columns feature), Python (with the pandas library), or other data preparation tools. The goal is to have one row per activity, with columns for ExpenseReportId, ActivityName, and EventTime.
Save the transformed data as a CSV file and upload it to the ProcessMind application.

Configuration

Admin Permissions: You must have Domain Admin or Policy Admin permissions for the relevant policy to create and manage export formats.
Export Template: A custom export template must be configured. This method will not work with the default templates.
Date Range: It is highly recommended to filter the export by a specific date range, such as 3-6 months, to keep the export process timely and the resulting file size manageable. Use the Submitted Date as the primary filter.
Report Status Filter: To capture the entire process lifecycle, avoid filtering by report status. Export all reports within the date range, including Open, Processing, Approved, Reimbursed, and Closed statuses.
Custom Fields: Attributes like EmployeeDepartment rely on your organization's specific Expensify configuration. If you use Tags or Report Fields for this information, you must add the corresponding formula, for example {report:tag:Department}, to the export template.

a Sample Query config

/*
This is not a script, but a configuration for the Expensify custom export template.
In the export format editor, create a new column for each line below, using the text on the right as the formula.
*/

// Case ID and Required Attributes
ExpenseReportId: {report:id}
EventTime_Created: {report:created}
EventTime_Submitted: {report:submitted}
EventTime_Approved: {report:approved}
EventTime_Reimbursed: {report:reimbursed}
EventTime_Closed: {report:closed}

// Recommended Attributes
ReportTotalAmount: {report:total}
Submitter: {report:submitter:email}
Approver: {report:approverEmail}
EmployeeDepartment: {report:tag:[Your Department Tag Name]}
PolicyViolationFlag: {report:hasViolations}

// --- Transformation Logic Overview ---
/*
After exporting the CSV with the columns above, you must unpivot the timestamp columns.
1. Load the CSV into a data transformation tool (e.g., Excel Power Query, Python pandas).
2. Select all the timestamp columns (EventTime_Created, EventTime_Submitted, etc.).
3. Use the "Unpivot" function. This will create two new columns: one containing the original column names (e.g., 'EventTime_Created') and another with the timestamp values.
4. Rename the column with the names to `ActivityName` and the column with values to `EventTime`.
5. Clean up the `ActivityName` column by removing the 'EventTime_' prefix to get clean activity names like 'Expense Report Created', 'Expense Report Submitted', etc.
6. For activities that do not have a direct timestamp export (e.g., 'Manager Approved', 'Reimbursement Scheduled'), you can duplicate an existing timestamp column (like 'EventTime_Approved') in your export template and rename it accordingly (e.g., `EventTime_ManagerApproved`). This uses the same timestamp as a proxy for multiple events, which should be noted during analysis.
*/

Your Expense Management Data Template

Your Expense Management Data Template

Expense Management Attributes

Expense Management Activities

Extraction Guides

Expensify Built-in Custom Report Export to CSV

Steps

Configuration

a Sample Query config

Python Script Extraction via the Expensify Public API

Steps

Configuration

a Sample Query python

Data Extraction using a Third-Party ETL Connector

Steps

Configuration

a Sample Query config

Ready to Get Started?

Optimize Expense Management: Start Your Free Trial Today

Your Expense Management Data Template

Your Expense Management Data Template

Expense Management Attributes

Expense Management Activities

Extraction Guides

Expensify Built-in Custom Report Export to CSV

Steps

Configuration

a Sample Query config

Python Script Extraction via the Expensify Public API

Steps

Configuration

a Sample Query python

Data Extraction using a Third-Party ETL Connector

Steps

Configuration

a Sample Query config

We value your privacy

Ready to Get Started?

Optimize Expense Management: Start Your Free Trial Today