> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sync2books.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Expenses

> This guide will help you set up your Expenses integration and make your first expense sync.

This guide will help you set up your Expenses integration and make your first expense sync.

## Overview

When implementing your Expenses solution, you need to:

1. **Create a company** - Represent your SMB customer in Sync2Books
2. **Create an accounting connection** - Connect to your customer's accounting software
3. **Configure expense mapping** - Set up default accounts, suppliers, and tax rates
4. **Create expense transactions** - Submit expenses for sync
5. **Monitor sync status** - Track the sync process and handle any errors

## Prerequisites

Before you begin, ensure you have:

* ✅ **API Key** — your application's API key from the [Sync2Books Dashboard](https://sync2books.com/dashboard). Getting and using your key (and the optional request signature) is covered once in [Authentication](/concepts/authentication).
* ✅ **Access to accounting software** — your customer's QuickBooks, Xero, or Sage account credentials.

<Note>
  Authentication, the company/connection object model, and the asynchronous sync flow
  are **shared across every Sync2Books product**. If you haven't already, skim
  [Core concepts](/concepts/authentication) — this guide builds directly on it.
</Note>

## Step 1: Create a company

Within Expenses, a company represents your SMB customer that manages their expenses using your application. To create it, use our Create company endpoint. It returns a JSON response containing the company `id`. You will use this `id` to establish a connection to an accounting software.

#### Request

```bash theme={null}
POST /companies

{
    "name": "{companyName}"
}
```

#### Response

```json theme={null}
{
  "company": {
    "id": "77921ff9-2491-4dfe-b23b-ff28f3e31e4f",
    "name": "Sawayn Group",
    "isActive": true
  },
  "authUrl": "https://appcenter.intuit.com/connect/oauth2?..."
}
```

## Step 2: Create accounting connection

Next, use the authorization URL returned when creating a company to connect the company to an accounting data source via one of our integrations. This will allow you to synchronize data with that source.

### QuickBooks Online

1. Open the `authUrl` from the company creation response in a browser
2. Complete the OAuth authorization flow with QuickBooks
3. After authorization, the connection is automatically created

You can also get the authorization URL for an existing company:

```bash theme={null}
curl -X GET "https://api.sync2books.com/companies/{companyId}/auth-url?integrationKey=quickbooks" \
  -H "X-API-Key: {apiKey}"
```

#### Response

```json theme={null}
[
  {
    "id": "7baba7cc-4ae0-48fd-a617-98d55a6fc008",
    "integrationKey": "quickbooks",
    "companyId": "77921ff9-2491-4dfe-b23b-ff28f3e31e4f",
    "status": "connected"
  }
]
```

## Step 3: Configure expense mapping (optional)

Before creating expenses, you can configure default mappings at the company level. This ensures expenses are automatically categorized correctly even if specific references are omitted.

#### Request

```bash theme={null}
PATCH /companies/{companyId}/expense-config

{
  "bankAccount": {
    "id": "bank-account-id"
  },
  "supplier": {
    "id": "supplier-id"
  },
  "defaultAccount": {
    "id": "expense-account-id"
  },
  "defaultTaxRate": {
    "id": "tax-rate-id"
  }
}
```

See [Map transactions](/expenses-map-transactions) for detailed configuration options.

## Step 4: Create your first expense

Now that you have a company and connection set up, you can create expense transactions:

#### Request

```bash theme={null}
POST /expenses/{connectionId}

{
  "id": "expense-001",
  "type": "Payment",
  "issueDate": "2024-01-15T00:00:00Z",
  "currency": "USD",
  "currencyRate": 1,
  "merchantName": "Office Supplies Co",
  "contactRef": {
    "id": "supplier-id",
    "type": "Supplier"
  },
  "bankAccountRef": {
    "id": "bank-account-id"
  },
  "lines": [
    {
      "netAmount": 100.00,
      "taxAmount": 10.00,
      "taxRateRef": {
        "id": "tax-rate-id"
      },
      "accountRef": {
        "id": "expense-account-id"
      }
    }
  ],
  "notes": "Office supplies for Q1 2024",
  "postAsDraft": false
}
```

#### Response

```json theme={null}
{
  "syncBatchId": "550e8400-e29b-41d4-a716-446655440000",
  "totalExpenses": 1
}
```

The response includes a `syncBatchId` that you can use to monitor the sync status.

## Step 5: Monitor sync status

Use the `syncBatchId` to monitor the sync progress:

#### Request

```bash theme={null}
GET /sync/batches/{syncBatchId}
```

#### Response

```json theme={null}
{
  "batch": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "companyId": "77921ff9-2491-4dfe-b23b-ff28f3e31e4f",
    "connectionId": "7baba7cc-4ae0-48fd-a617-98d55a6fc008",
    "status": "completed",
    "totalItems": 1,
    "successfulItems": 1,
    "failedItems": 0,
    "createdAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:00:05Z"
  },
  "items": [
    {
      "id": "item-uuid-1",
      "entityId": "expense-001",
      "entityType": "Expense",
      "status": "success",
      "integrationResponse": {
        "id": "qb-expense-id",
        "syncToken": "0"
      },
      "syncErrorMessage": null,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:05Z"
    }
  ]
}
```

See [Sync transactions](/expenses-sync-transactions) for detailed status tracking and error handling.

## Recap

You have created the structure of key objects required by Sync2Books Expenses: a company and its connection to an accounting data source. You've also created and synced your first expense transaction.

## Read next

* [Configure customer](/expenses-configure-customer) - Learn how to set up companies and connections
* [Map transactions](/expenses-map-transactions) - Configure expense mapping preferences
* [Create transactions](/expenses-create-transactions) - Learn how to create expense transactions
* [Sync transactions](/expenses-sync-transactions) - Understand the sync process
* [Upload receipts](/expenses-upload-receipts) - Attach files to expenses