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 organizational collections that can span multiple companies in multi-company accounts.

Single-Company Account:

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

Multi-Company Account:

Structural Hierarchy:
Ottimate Account (racc_xxx)
│
├── Company 1 (ottimate_company_id: 123)
│   ├── Chart of Accounts (Dimensions)
│   ├── Vendor List
│   └── Locations
│       ├── Location A (ottimate_location_id: 456)
│       └── Location B (ottimate_location_id: 457)
│
└── Company 2 (ottimate_company_id: 789)
    ├── Chart of Accounts (Dimensions)
    ├── Vendor List
    └── Locations
        ├── Location D (ottimate_location_id: 460)
        └── Location E (ottimate_location_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)

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.

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:

1
{
2
  "count": 2,
3
  "page": 1,
4
  "limit": 10,
5
  "next": null,
6
  "previous": null,
7
  "results": [
8
    {
9
      "id": 123,
10
      "name": "Acme Inc.",
11
      "location_count": 5
12
    },
13
    {
14
      "id": 124,
15
      "name": "Acme Inc. - Downtown",
16
      "location_count": 1
17
    }
18
  ]
19
}

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:

1
{
2
  "count": 5,
3
  "page": 1,
4
  "limit": 10,
5
  "next": null,
6
  "previous": null,
7
  "results": [
8
    {
9
      "id": 456,
10
      "name": "Main Kitchen",
11
      "company": "Acme Inc.",
12
      "group": "West Region"
13
    },
14
    {
15
      "id": 457,
16
      "name": "Downtown Branch",
17
      "company": "Acme Inc.",
18
      "group": "West Region"
19
    },
20
    {
21
      "id": 458,
22
      "name": "East Side Location",
23
      "company": "Acme Inc.",
24
      "group": "East Region"
25
    }
26
  ]
27
}

Response Fields:

Groups

A group is an optional organizational collection of one or more locations within an account. Groups provide flexibility for organizing locations for reporting, permissions, and workflow management.

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
• Returned in the group field of the Location object
• Groups are read-only via API (configured through Ottimate Onboarding Tool)

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”: