> This page is for version V1 (default).
> For other versions, use one of these documentation indexes:
> - V1 (default): https://docs.ottimate.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ottimate.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server.

# Integration Patterns & Best Practices

## Provisioning Workflow

### What Ottimate Configures (Before You Start)

During the onboarding process, Ottimate configures:

1. **Client Account** - Top-level account entity with unique `racc_` identifier
2. **Company Structure** - One or more companies based on the client's accounting structure
3. **Location Setup** - All locations within each company
4. **Groups** (if applicable) - Location groupings for multi-company accounts
5. **API Credentials** - Client ID and Client Secret for OAuth authentication scoped to an API User
6. **Feature Enablement** - Activates features based on client subscription (InstantCapture, Catalog Match, etc.)
7. **ERP Connection** (if applicable) - Configures Ottimate-hosted ERP integrations

**By the time you receive API credentials, your account structure is fully configured and ready for integration.**

### What You Verify First

After receiving your Sandbox credentials:

1. **Verify account structure** - List companies and locations to understand the hierarchy
2. **Test API User scope** - Confirm you can access all required companies/locations
3. **Map identifiers** - Create a mapping between your system's IDs and the company and location `id` values Ottimate returns. Those IDs are sent under different names depending on the endpoint — see [Identifier naming across endpoints](/account-structure/overview#identifier-naming-across-endpoints).

```bash
# Step 1: List companies
GET /v1/accounts/{account_id}/companies

# Step 2: List locations
GET /v1/accounts/{account_id}/locations

# Step 3: Verify access to specific resources
GET /v1/vendors?ottimate_company_id=123
GET /v1/invoices?ottimate_company_id=123&ottimate_location_id=456
```

### What You Configure via API

After verifying your account structure, you'll typically:

1. **Sync Dimensions** - Push or pull chart of accounts from the ERP
2. **Sync Vendors** - Push or pull vendor list from the ERP
3. **Configure Catalog** (optional) - Sync inventory items for catalog matching
4. **Test Invoice Creation** - Create test invoices to validate the workflow

See [Accounting Integration](/accounting) for detailed sync procedures.

### Managing Changes

| Change Type                                           | Method                                                             |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| Add/modify dimensions                                 | API: `POST /v1/dimensions` or `POST /v1/dimensions/bulk`           |
| Add/modify vendors                                    | API: `POST /v1/vendors` or `POST /v1/vendors/bulk`                 |
| Add/modify catalog entries                            | API: `POST /v1/catalog/entries` or `POST /v1/catalog/entries/bulk` |
| Modify account structure (companies/locations/groups) | Contact Ottimate Partner Manager                                   |
| Change API User scope                                 | Contact Ottimate Partner Manager                                   |
| Change ERP connection                                 | Contact Ottimate Partner Manager                                   |

---

## Common Integration Patterns

### Pattern 1: Single Company, Single Location

**Use Case:** Small business with centralized AP

```
Account: Small Business Inc
└── Company: Small Business Inc
    └── Location: Headquarters
```

**API Usage:**

* All requests use the same `ottimate_company_id`
* All invoices use the same `ottimate_location_id`
* Simplest integration pattern

**Example:**

```bash
# All API calls use the same IDs
POST /v1/invoices
{
  "ottimate_company_id": 123,
  "ottimate_location_id": 456,
  ...
}
```

---

### Pattern 2: Single Company, Multiple Locations

**Use Case:** Restaurant chain, retail chain, or multi-site business

```
Account: Restaurant Group
└── Company: Restaurant Group Inc
    ├── Location: Store #001
    ├── Location: Store #002
    └── Location: Store #003
```

**API Usage:**

* All requests use the same `ottimate_company_id`
* Invoices are assigned to appropriate `ottimate_location_id` based on which location received the goods/services
* Vendors and dimensions are shared across all locations

**Integration Considerations:**

* Map your system's location identifiers to Ottimate location IDs
* Route invoices to correct location based on purchase order, delivery address, or other business logic
* Users may be restricted to view only their assigned locations

---

### Pattern 3: Multiple Companies

**Use Case:** Holding company, MSP managing multiple clients

```
Account: Holding Company
├── Company: Subsidiary A (NetSuite)
│   ├── Location: HQ
│   └── Location: Warehouse
└── Company: Subsidiary B (QuickBooks)
    └── Location: Office
```

**API Usage:**

* Each company has separate dimensions, vendors, and invoices
* No data sharing between companies
* Each company typically connects to a different ERP instance

**Integration Considerations:**

* Maintain separate dimension/vendor mappings per company
* Handle each company's invoice workflow independently
* May require separate sync schedules per company

---

## Best Practices

* **Verify structure first** - Before writing integration code, list all companies and locations to understand the account hierarchy and your API User's access scope.
* **Document mappings** - Maintain a clear mapping between your system's identifiers and Ottimate's `company_id` and `location_id` values.
* **Understand your API User scope** - Test which companies/locations you can access. Don't assume account-level access.
* **Cache company/location lists** - Account structure rarely changes, so fetch once during initialization and cache locally. Note that `GET /v1/accounts/{account_id}/locations` returns **active locations only** and has no way to include de-activated ones, so a cached location that stops appearing on a later fetch has been de-activated — retire it from your routing rather than treating the omission as an error. See [Locations](/account-structure/overview#locations).
* **Validate scope before creation** - Always verify that `ottimate_company_id` and `ottimate_location_id` exist and are correctly paired before creating invoices.
* **Test with production structure** - Ensure your Sandbox environment mirrors your production account structure for accurate testing.
* **Refresh mappings periodically** - If your client adds new locations, implement a process to refresh your location mappings.

---

## Next Steps

Now that you understand account structure and integration patterns, proceed to set up accounting data:

#### [Accounting Integration](/accounting)

Learn how to sync accounting data between your ERP and Ottimate

#### [Dimensions](/dimensions)

Sync your chart of accounts and other dimensions

#### [Vendors](/vendors)

Set up and manage your vendor list

#### [Invoices](/invoices)

Start creating and processing invoices