Skip to main content

​
Overview

This page documents commonly used API endpoints in New Expensify. For the complete list of endpoints, see src/libs/API/types.ts in the repository.
All API endpoints are defined in src/libs/API/types.ts with their parameter types in src/libs/API/parameters/.

​
Endpoint Categories

​
Authentication

​
Reports & Chat

​
Money Requests (IOU)

​
Workspaces (Policies)

​
Transactions

​
Authentication Endpoints

​
SignIn

Authenticate a user with email and password. Type: WRITE Parameters: 
type SignInParams = {
  email: string;
  password: string;
  twoFactorAuthCode?: string;
};
Example: 
import API from '@libs/API';

function signIn(email: string, password: string) {
  API.write('SignIn', {email, password});
}

​
SignOut

Sign out the current user. Type: WRITE Parameters: None Example: 
API.write('SignOut', {});

​
Reauthenticate

Refresh authentication token. Type: WRITE Parameters: 
type ReauthenticateParams = {
  useExpensifyLogin: boolean;
  partnerName: string;
  partnerPassword: string;
  twoFactorAuthCode?: string;
};
Example: Handled automatically by middleware.

​
ValidateEmail

Validate user’s email with validation code. Type: WRITE Parameters: 
type ValidateEmailParams = {
  validateCode: string;
};

​
Reports & Chat Endpoints

​
OpenReport

Load report data and mark as read. Type: READ Parameters: 
type OpenReportParams = {
  reportID: string;
  emailList?: string;
  accountIDList?: string;
};
Example: 
function openReport(reportID: string) {
  const optimisticData: OnyxUpdate[] = [
    {
      onyxMethod: Onyx.METHOD.MERGE,
      key: `${ONYXKEYS.COLLECTION.REPORT_METADATA}${reportID}`,
      value: {isLoadingInitialReportActions: true},
    },
  ];

  API.read('OpenReport', {reportID}, {optimisticData});
}

​
AddComment

Add a comment/message to a report. Type: WRITE Parameters: 
type AddCommentParams = {
  reportID: string;
  reportComment: string;
  reportActionID?: string;
};
Example: 
function addComment(reportID: string, message: string) {
  const reportActionID = generateRandomID();
  
  const optimisticData: OnyxUpdate[] = [
    {
      onyxMethod: Onyx.METHOD.MERGE,
      key: `${ONYXKEYS.COLLECTION.REPORT_ACTIONS}${reportID}`,
      value: {
        [reportActionID]: {
          reportActionID,
          message: [{type: 'COMMENT', html: message, text: message}],
          person: [currentUserPersonalDetails],
          created: new Date().toISOString(),
          pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
        },
      },
    },
  ];

  API.write('AddComment', {
    reportID,
    reportComment: message,
    reportActionID,
  }, {optimisticData, successData, failureData});
}

​
DeleteComment

Delete a comment from a report. Type: WRITE Parameters: 
type DeleteCommentParams = {
  reportID: string;
  reportActionID: string;
};

​
TogglePinnedChat

Pin or unpin a chat. Type: WRITE Parameters: 
type TogglePinnedChatParams = {
  reportID: string;
  pinnedValue: boolean;
};
Example: 
function togglePinned(reportID: string, isPinned: boolean) {
  const optimisticData: OnyxUpdate[] = [
    {
      onyxMethod: Onyx.METHOD.MERGE,
      key: `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
      value: {isPinned: !isPinned},
    },
  ];

  API.write('TogglePinnedChat', {
    reportID,
    pinnedValue: !isPinned,
  }, {optimisticData});
}

​
Money Request Endpoints

​
RequestMoney

Create a money request. Type: WRITE Parameters: 
type RequestMoneyParams = {
  debtorEmail?: string;
  debtorAccountID?: number;
  amount: number;
  currency: string;
  comment: string;
  merchant: string;
  created: string;
  reportID: string;
  transactionID: string;
  reportActionID: string;
  category?: string;
  tag?: string;
  billable?: boolean;
};
Example: 
function requestMoney(
  report: Report,
  amount: number,
  currency: string,
  merchant: string,
) {
  const transactionID = generateRandomID();
  const reportActionID = generateRandomID();
  
  const optimisticData: OnyxUpdate[] = [
    // Create optimistic transaction
    {
      onyxMethod: Onyx.METHOD.SET,
      key: `${ONYXKEYS.COLLECTION.TRANSACTION}${transactionID}`,
      value: {
        transactionID,
        amount,
        currency,
        merchant,
        created: new Date().toISOString(),
        pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
      },
    },
    // Add report action
    {
      onyxMethod: Onyx.METHOD.MERGE,
      key: `${ONYXKEYS.COLLECTION.REPORT_ACTIONS}${report.reportID}`,
      value: {
        [reportActionID]: {
          reportActionID,
          actionName: CONST.REPORT.ACTIONS.TYPE.IOU,
          originalMessage: {IOUTransactionID: transactionID},
          pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
        },
      },
    },
  ];

  API.write('RequestMoney', {
    reportID: report.reportID,
    amount,
    currency,
    merchant,
    transactionID,
    reportActionID,
  }, {optimisticData, successData, failureData});
}

​
CreateDistanceRequest

Create a distance-based expense request. Type: WRITE Parameters: 
type CreateDistanceRequestParams = {
  comment: string;
  created: string;
  transactionID: string;
  reportActionID: string;
  waypoints: string; // JSON string
  routes: string;    // JSON string
};

​
SplitBill

Split an expense among multiple participants. Type: WRITE Parameters: 
type SplitBillParams = {
  reportID: string;
  amount: number;
  currency: string;
  comment: string;
  merchant: string;
  created: string;
  splits: string; // JSON array of {email, amount}
  transactionID: string;
};

​
PayMoneyRequest

Pay a money request. Type: WRITE Parameters: 
type PayMoneyRequestParams = {
  reportID: string;
  reportActionID: string;
  paymentMethodType: 'Expensify' | 'Elsewhere';
  full: boolean;
};

​
Workspace Endpoints

​
CreateWorkspace

Create a new workspace/policy. Type: WRITE Parameters: 
type CreateWorkspaceParams = {
  policyID: string;
  policyName: string;
  makeMeAdmin?: boolean;
};
Example: 
function createWorkspace(policyName: string) {
  const policyID = generateRandomID();
  
  const optimisticData: OnyxUpdate[] = [
    {
      onyxMethod: Onyx.METHOD.SET,
      key: `${ONYXKEYS.COLLECTION.POLICY}${policyID}`,
      value: {
        id: policyID,
        name: policyName,
        type: CONST.POLICY.TYPE.TEAM,
        role: CONST.POLICY.ROLE.ADMIN,
        pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
      },
    },
  ];

  API.write('CreateWorkspace', {
    policyID,
    policyName,
  }, {optimisticData, successData, failureData});
}

​
UpdateWorkspace

Update workspace settings. Type: WRITE Parameters: 
type UpdateWorkspaceParams = {
  policyID: string;
  name?: string;
  description?: string;
  avatarURL?: string;
};

​
DeleteWorkspace

Delete a workspace. Type: WRITE Parameters: 
type DeleteWorkspaceParams = {
  policyID: string;
};

​
InviteMembersToWorkspace

Invite members to a workspace. Type: WRITE Parameters: 
type InviteMembersToWorkspaceParams = {
  policyID: string;
  employees: string; // JSON array of {email, role}
  welcomeNote?: string;
};

​
Transaction Endpoints

​
UpdateTransaction

Update transaction details. Type: WRITE Parameters: 
type UpdateTransactionParams = {
  transactionID: string;
  amount?: number;
  merchant?: string;
  comment?: string;
  category?: string;
  tag?: string;
  billable?: boolean;
};

​
DeleteTransaction

Delete a transaction. Type: WRITE Parameters: 
type DeleteTransactionParams = {
  transactionID: string;
  reportID: string;
  reportActionID: string;
};

​
HoldRequest

Put a money request on hold. Type: WRITE Parameters: 
type HoldRequestParams = {
  transactionID: string;
  reportActionID: string;
  comment: string;
};

​
UnholdRequest

Remove hold from a money request. Type: WRITE Parameters: 
type UnholdRequestParams = {
  transactionID: string;
  reportActionID: string;
};

​
Using Endpoints

​
Basic Pattern

import API from '@libs/API';
import type {OnyxUpdate} from '@src/types/onyx/Request';

function myAPICall(params: MyParams) {
  // 1. Prepare optimistic data
  const optimisticData: OnyxUpdate[] = [...];
  
  // 2. Prepare success data
  const successData: OnyxUpdate[] = [...];
  
  // 3. Prepare failure data
  const failureData: OnyxUpdate[] = [...];
  
  // 4. Make API call
  API.write('MyCommand', params, {
    optimisticData,
    successData,
    failureData,
  });
}

​
Finding Endpoint Usage

To see how an endpoint is used: 
# Search for endpoint usage in codebase
grep -r "API.write('CreateWorkspace'" src/

# Find parameter type
# Look in src/libs/API/parameters/CreateWorkspaceParams.ts

​
Best Practices

​
1. Use Defined Types

import type {CreateWorkspaceParams} from '@libs/API/parameters';

// ✅ Good: Use the defined type
const params: CreateWorkspaceParams = {
  policyID,
  policyName,
};

// ❌ Bad: Inline object
API.write('CreateWorkspace', {
  policyID,
  policyName,
});

​
2. Always Include Onyx Data

// ✅ Good: Complete Onyx data
API.write('CreateWorkspace', params, {
  optimisticData,
  successData,
  failureData,
});

// ❌ Bad: Missing failure data
API.write('CreateWorkspace', params, {
  optimisticData,
});

​
3. Generate IDs Client-Side

// ✅ Good: Generate ID before API call
const reportActionID = generateRandomID();
API.write('AddComment', {reportActionID, ...});

// ❌ Bad: Wait for server to generate ID
API.write('AddComment', {...}); // Server generates ID

​
Next Steps

API Overview

Understand API fundamentals

Authentication

Learn authentication flows

State Management

Understand Onyx integration

Source Code

View all endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us