API Endpoints Reference - New Expensify

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 Endpoints

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

Architecture

Contributing

API Reference

Documentation Index

​Overview

​Endpoint Categories

​Authentication

​Reports & Chat

​Money Requests (IOU)

​Workspaces (Policies)

​Transactions

​Authentication Endpoints

​SignIn

​SignOut

​Reauthenticate

​ValidateEmail

​Reports & Chat Endpoints

​OpenReport

​AddComment

​DeleteComment

​TogglePinnedChat

​Money Request Endpoints

​RequestMoney

​CreateDistanceRequest

​SplitBill

​PayMoneyRequest

​Workspace Endpoints

​CreateWorkspace

​UpdateWorkspace

​DeleteWorkspace

​InviteMembersToWorkspace

​Transaction Endpoints

​UpdateTransaction

​DeleteTransaction

​HoldRequest

​UnholdRequest

​Using Endpoints

​Basic Pattern

​Finding Endpoint Usage

​Best Practices

​1. Use Defined Types

​2. Always Include Onyx Data

​3. Generate IDs Client-Side

​Next Steps

API Overview

Authentication

State Management

Source Code

Overview

Endpoint Categories

Authentication

Reports & Chat

Money Requests (IOU)

Workspaces (Policies)

Transactions

Authentication Endpoints

SignIn

SignOut

Reauthenticate

ValidateEmail

Reports & Chat Endpoints

OpenReport

AddComment

DeleteComment

TogglePinnedChat

Money Request Endpoints

RequestMoney

CreateDistanceRequest

SplitBill

PayMoneyRequest

Workspace Endpoints

CreateWorkspace

UpdateWorkspace

DeleteWorkspace

InviteMembersToWorkspace

Transaction Endpoints

UpdateTransaction

DeleteTransaction

HoldRequest

UnholdRequest

Using Endpoints

Basic Pattern

Finding Endpoint Usage

Best Practices

1. Use Defined Types

2. Always Include Onyx Data

3. Generate IDs Client-Side

Next Steps