Account Structure

Overview

Ottimate uses a tiered organizational hierarchy to manage accounts payable operations. Understanding this structure is essential for integration because every API request must be properly scoped to the correct company and location.

The hierarchy consists of:

1. Account - The top-level organization (an Ottimate client)
2. Company - A distinct accounting entity with its own chart of accounts and vendors
3. Location - A subdivision within a company for invoice processing and approvals

Additionally, locations can be organized into Groups - optional labels that can span multiple companies in multi-company accounts.

Single-Company Account:

Structural Hierarchy:
Ottimate Account (racc_xxx)
│
└── Company 1 (id: 123)
    ├── Chart of Accounts (Dimensions)
    ├── Vendor List
    └── Locations
        ├── Location A (id: 456)
        ├── Location B (id: 457)
        ├── Location C (id: 458)
        └── Location D (id: 459)
Optional Groups (labels only):
├── North Region → Locations A, B
└── South Region → Locations C, D

Multi-Company Account:

Structural Hierarchy:
Ottimate Account (racc_xxx)
│
├── Company 1 (id: 123)
│   ├── Chart of Accounts (Dimensions)
│   ├── Vendor List
│   └── Locations
│       ├── Location A (id: 456)
│       └── Location B (id: 457)
│
└── Company 2 (id: 789)
    ├── Chart of Accounts (Dimensions)
    ├── Vendor List
    └── Locations
        ├── Location D (id: 460)
        └── Location E (id: 461)
Groups (can span across companies):
├── West Region → Location A (Company 1), Location D (Company 2)
└── East Region → Location B (Company 1), Location E (Company 2)

Identifier naming across endpoints

The Accounts API returns companies and locations with a plain id. That same value is what you pass on the other endpoints, where it is named for the entity it points at:

There is no ottimate_company_id or ottimate_location_id field in an Accounts API response — those names only ever appear in requests to other APIs.

Hierarchy Components

Client Accounts (racc_)

A client account represents an organization using Ottimate to automate accounts payable processes. This is the top-level entity that Ottimate provisions during onboarding.

Key Characteristics:

• Unique identifier format: racc_ prefix (e.g., racc_90832490382904802384)
• Contains one or more companies
• API credentials (Client ID, Client Secret) are scoped to an account
• Billing and subscription are managed at the account level

For API Integrators

Accounts are provisioned by Ottimate during the Onboarding process before you begin integration development. By the time you receive your API credentials, your account structure (account, companies, and locations) is already configured.

Listing the accounts you can reach:

Your credentials may be scoped to more than one account. GET /v1/accounts returns every account your API user can access, which is where an integration usually starts.

{
  "version": "1.0.0",
  "count": 1,
  "page": 1,
  "limit": 50,
  "results": [
    {
      "id": "racc_a1b2c3d4e5f6",
      "name": "Acme Restaurant Group",
      "created_date": "2024-01-15T10:30:00Z",
      "created_date_utc": "2024-01-15T10:30:00.000000Z",
      "company_count": 5,
      "location_count": 23
    }
  ]
}

Response Fields:

Companies

A company is a distinct accounting entity within a client account. Each company maintains its own:

When to Use Multiple Companies

Use separate companies when:

Use a single company with multiple locations when:

Examples

Multi-Company Scenario:

Restaurant Group (Account)
├── Brand A LLC (Company 1) - Uses NetSuite
│   └── 50 Brand A locations
└── Brand B Corp (Company 2) - Uses QuickBooks
    └── 30 Brand B locations

Single-Company Scenario:

Regional Restaurant Chain (Account)
└── ABC Restaurants Inc (Company 1) - Uses NetSuite
    ├── Boston Location
    ├── New York Location
    └── Philadelphia Location

Accessing Company Information

Companies are pre-configured during account onboarding. Use the companies endpoint to retrieve company IDs for your API calls:

List Companies Example:

GET https://api.ottimate.com/v1/accounts/racc_90832490382904802384/companies

Response:

{
  "version": "1.0.0",
  "count": 2,
  "page": 1,
  "limit": 10,
  "results": [
    {
      "id": 123,
      "name": "Acme Inc.",
      "location_count": 5,
      "plan": null
    },
    {
      "id": 124,
      "name": "Acme Inc. - Downtown",
      "location_count": 1,
      "plan": null
    }
  ]
}

Response Fields:

Locations

A location is a subdivision within a company used to organize invoice processing, permissions, and approval workflows. Locations share the same chart of accounts and vendor list as their parent company.

Key Characteristics:

• Belongs to exactly one company
• Shares the company’s dimensions and vendors
• Can have location-specific approval policies
• Can have location-specific user permissions
• Can have location-specific email to receive invoices
• Used to route invoices to appropriate approvers

Accessing Location Information

Locations are pre-configured during account onboarding. Use the locations endpoint to retrieve location IDs for invoice creation and filtering:

List Locations Example:

GET https://api.ottimate.com/v1/accounts/racc_90832490382904802384/locations

Response:

{
  "version": "1.0.0",
  "count": 3,
  "page": 1,
  "limit": 10,
  "results": [
    {
      "id": 456,
      "name": "Main Kitchen",
      "company": "Acme Inc.",
      "company_id": 123,
      "group": "West Region",
      "uses_approval": true
    },
    {
      "id": 457,
      "name": "Downtown Branch",
      "company": "Acme Inc.",
      "company_id": 123,
      "group": "West Region",
      "uses_approval": false
    },
    {
      "id": 458,
      "name": "East Side Location",
      "company": "Acme Inc.",
      "company_id": 123,
      "group": "East Region",
      "uses_approval": false
    }
  ]
}

Response Fields:

API versioning

The Accounts API supports two versions, selected with the X-API-Version request header:

Every response echoes the version that rendered it in its top-level version field, so you can confirm which one you got.

Migrating from group to location_group:

curl https://api.ottimate.com/v1/accounts/racc_90832490382904802384/locations \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Version: 1.1.0"

The two fields carry the same value, so migration is a rename: send the 1.1.0 header and read location_group. group is still returned for 1.0.0 and unversioned requests.

Groups

A group is an optional label applied to a location, used for reporting, permissions, and workflow management within Ottimate. Groups are not a scoping tier for the API: no request is scoped to a group, and nothing is inherited through one.

Key Characteristics:

• A group contains 1 or more locations
• A location can only belong to 1 group (or none)
• Groups are optional - locations can exist without being assigned to a group
• Groups are configured through the Ottimate Onboarding Tool, not the API

Groups in Single-Company Accounts:

In a single-company account, groups organize locations within the same company:

Groups in Multi-Company Accounts (Cross-Company Groups):

In multi-company accounts, groups can span across companies, creating “cross-company groups”: