> 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.

# Preview coding defaults for a location + vendor

GET https://api.ottimate.com/v1/coding-defaults

Returns the GL and dimension coding defaults for the given `ottimate_location_id` and `erp_vendor_id`, without creating an invoice. Use this to pre-fill an invoice-capture UI before calling `POST /invoices` — pass the returned `erp_dimension_id` values through to that endpoint's `dimensions` field to persist them. Every response includes three previews: header-level defaults (`header_dimensions`), line-item defaults that apply to every line (`all_line_items`), and line-item defaults keyed by item description (`by_item_description`).

Reference: https://docs.ottimate.com/api-reference/api-reference/coding-defaults/get-coding-defaults-root

## Authentication

- `Authorization` header (bearer token, required) — OAuth2 authentication flows. Auth server URLs will vary by environment

## Servers

- `https://api.ottimate.com/v1` (Production, default)
- `https://sandbox-api.ottimate.com/v1` (Sandbox)

## Request

### Query parameters

- `ottimate_location_id` (integer, required) — Restaurant/location ID, same value used on invoice create.
- `erp_vendor_id` (string, required) — ERP accounting vendor ID (the `accounting_id` on the vendor record). Matched case-insensitively.
- `applies_to` (enum, optional, default: header) — Which mapping rule scope to evaluate for `header_dimensions`. Only `header` is supported. This does not affect `all_line_items` or `by_item_description`, which are always returned.
  - Allowed values: `header`
- `item_description` (string, optional) — When provided, scopes `by_item_description` to a single lookup for this item description (matched using the same fuzzy-normalization logic as invoice processing). When omitted, `by_item_description` returns all configured item-description defaults for this location + vendor, paginated via `page`/`limit`.
- `charge_type` (enum, optional) — When provided, scopes `all_line_items` to the matching charge-type bucket. Only meaningful when the account has Charge Type Categorization enabled — otherwise this parameter is ignored and `all_line_items` is returned as if it were omitted.
  - Allowed values: `FREIGHT`, `MISC`, `TAX`
- `page` (integer, optional, default: 1) — Page number for paginating `by_item_description` when `item_description` is not set, starting at 1. Requesting a page past the last one returns an empty `by_item_description.results` list.
- `limit` (integer, optional, default: 20) — Page size for paginating `by_item_description` when `item_description` is not set.

### Headers

- `X-Api-Key` (string, required) — API key for authentication
- `X-API-Version` (string, optional) — API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.

## Response

### 200

Successful response with coding defaults

- `ottimate_location_id` (integer, required) — The location ID this response was resolved for
- `erp_vendor_id` (string, required) — The ERP vendor ID this response was resolved for
- `accounting_mode` (enum, required) — Whether this location uses Enhanced Dimensions or legacy GL accounting
  - Allowed values: `enhanced_dimensions`, `legacy_gl`
- `header_dimensions` (map from string to CodingDefaultsGetResponsesContentApplicationJsonSchemaHeaderDimensions, required) — Header-level dimension defaults, keyed by dimension type (e.g. 'DEPARTMENT', 'CLASS'). Empty when accounting_mode is legacy_gl or no default applies.
- `vendor_coding` (CodingDefaultsGetResponsesContentApplicationJsonSchemaVendorCoding, required) — Vendor-level coding defaults for this location + vendor, regardless of accounting mode.
- `all_line_items` (list of CodingDefaultsGetResponsesContentApplicationJsonSchemaAllLineItemsItems, required) — Line-item defaults that apply to every line for this location + vendor pair, regardless of item description. One entry per charge-type bucket that has applicable rules, plus the null (standard item) bucket. Empty when legacy_gl or no default applies.
- `by_item_description` (CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescription, required) — Item-description-specific line-item defaults. A paginated object when `item_description` was omitted from the request, or a list of 0-1 entries when it was provided.
- `default_gl` (CodingDefaultsGetResponsesContentApplicationJsonSchemaDefaultGl, optional, nullable) — Default GL account. Populated for legacy_gl accounts, and also for enhanced_dimensions accounts that auto-map to a global default GL (source: 'default') — that path is not gated by accounting_mode.
- `warnings` (list of string, optional) — Response-specific caveats, e.g. a matched value that couldn't be resolved to a usable ID. Empty when nothing unusual applies to this particular location/vendor pair.

## Errors

### 400 Bad Request Error

Bad request - Invalid parameters or request format

- `code` (string, required) — Machine-readable error code: an app-specific prefix (e.g. 'INV' for invoices, 'RCPT' for receipts, 'CAT' for catalog) followed by a 4-digit code, e.g. INV4000 for a generic 4xx (validation, not found, etc).
- `message` (ErrorResponseMessage, required, nullable) — Additional error details, can be an object, a string, or null.
- `request_id` (string, optional) — Unique identifier for the request
- `timestamp` (string, optional) — Request timestamp in API Gateway's log format (not ISO 8601).

### 403 Forbidden Error

Forbidden - Access denied or insufficient permissions

- `Get_coding-defaults_rootRequestForbiddenError`
  - ErrorResponse
  - GatewayForbiddenResponse

### 404 Not Found Error

Not found - Resource does not exist

- `code` (string, required) — Machine-readable error code: an app-specific prefix (e.g. 'INV' for invoices, 'RCPT' for receipts, 'CAT' for catalog) followed by a 4-digit code, e.g. INV4000 for a generic 4xx (validation, not found, etc).
- `message` (ErrorResponseMessage, required, nullable) — Additional error details, can be an object, a string, or null.
- `request_id` (string, optional) — Unique identifier for the request
- `timestamp` (string, optional) — Request timestamp in API Gateway's log format (not ISO 8601).

## Types

### CodingDefaultsGetResponsesContentApplicationJsonSchemaHeaderDimensions

- `erp_dimension_id` (string, required) — Dimension ID as known in the client's ERP system — pass this value into POST /invoices dimensions.
- `source` (enum, required)
  - Allowed values: `mapping_rule`
- `code` (string, optional, nullable)
- `name` (string, optional, nullable)
- `rule_id` (string, optional, nullable)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaVendorCoding

Vendor-level coding defaults for this location + vendor, regardless of accounting mode.

- `erp_vendor_id` (string, required)
- `source` (enum, required) — not_configured when no vendor coding exists yet for this location + vendor.
  - Allowed values: `configured`, `not_configured`
- `ottimate_vendor_id` (integer, optional, nullable)
- `accounting_class` (CodingDefaultsGetResponsesContentApplicationJsonSchemaVendorCodingAccountingClass, optional, nullable)
- `default_department` (CodingDefaultsGetResponsesContentApplicationJsonSchemaVendorCodingDefaultDepartment, optional, nullable)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaAllLineItemsItems

- `charge_type` (enum, required, nullable)
  - Allowed values: `FREIGHT`, `MISC`, `TAX`
- `dimensions` (map from string to CodingDefaultsGetResponsesContentApplicationJsonSchemaAllLineItemsItemsDimensions, required) — Keyed by dimension type (e.g. 'DEPARTMENT', 'CLASS').

### CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescription

Item-description-specific line-item defaults. A paginated object when `item_description` was omitted from the request, or a list of 0-1 entries when it was provided.

- CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescription0
- list of CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf1Items

### CodingDefaultsGetResponsesContentApplicationJsonSchemaDefaultGl

Default GL account. Populated for legacy_gl accounts, and also for enhanced_dimensions accounts that auto-map to a global default GL (source: 'default') — that path is not gated by accounting_mode.

- `erp_dimension_id` (string, required) — GL account number / external ID
- `source` (enum, required)
  - Allowed values: `configured`, `default`
- `code` (string, optional, nullable)
- `name` (string, optional, nullable)
- `rule_id` (string, optional, nullable) — Always null here — no mapping rule is involved for GL defaults.

### ErrorResponseMessage

Additional error details, can be an object, a string, or null.

- map from string to any
- string

### ErrorResponse

- `code` (string, required) — Machine-readable error code: an app-specific prefix (e.g. 'INV' for invoices, 'RCPT' for receipts, 'CAT' for catalog) followed by a 4-digit code, e.g. INV4000 for a generic 4xx (validation, not found, etc).
- `message` (ErrorResponseMessage, required, nullable) — Additional error details, can be an object, a string, or null.
- `request_id` (string, optional) — Unique identifier for the request
- `timestamp` (string, optional) — Request timestamp in API Gateway's log format (not ISO 8601).

### GatewayForbiddenResponse

Bare API Gateway rejection (e.g. missing/invalid X-Api-Key), distinct from the app-level ErrorResponse envelope.

- `message` (string, required)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaVendorCodingAccountingClass

- `erp_dimension_id` (string, optional)
- `code` (string, optional, nullable)
- `name` (string, optional, nullable)
- `source` (enum, optional)
  - Allowed values: `configured`
- `rule_id` (string, optional, nullable) — Always null here — no mapping rule is involved for vendor coding.

### CodingDefaultsGetResponsesContentApplicationJsonSchemaVendorCodingDefaultDepartment

- `erp_dimension_id` (string, optional)
- `code` (string, optional, nullable)
- `name` (string, optional, nullable)
- `source` (enum, optional)
  - Allowed values: `configured`
- `rule_id` (string, optional, nullable) — Always null here — no mapping rule is involved for vendor coding.

### CodingDefaultsGetResponsesContentApplicationJsonSchemaAllLineItemsItemsDimensions

- `id` (string, required)
- `erp_dimension_id` (string, required, nullable)
- `name` (string, required)
- `code` (string, required, nullable)
- `display_name` (string, required)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescription0

List mode (item_description omitted).

- `count` (integer, required)
- `page` (integer, required)
- `limit` (integer, required)
- `results` (list of CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf0ResultsItems, required)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf1Items

- `item_description` (string, required)
- `dimensions` (map from string to CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf1ItemsDimensions, required)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf0ResultsItems

- `item_description` (string, required)
- `dimensions` (map from string to CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf0ResultsItemsDimensions, required)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf1ItemsDimensions

- `id` (string, required)
- `erp_dimension_id` (string, required, nullable)
- `name` (string, required)
- `code` (string, required, nullable)
- `display_name` (string, required)

### CodingDefaultsGetResponsesContentApplicationJsonSchemaByItemDescriptionOneOf0ResultsItemsDimensions

- `id` (string, required)
- `erp_dimension_id` (string, required, nullable)
- `name` (string, required)
- `code` (string, required, nullable)
- `display_name` (string, required)

## Examples

### Enhanced Dimensions account with a matching default

**Response**

```json
{
  "ottimate_location_id": 12345,
  "erp_vendor_id": "SYSCO-001",
  "accounting_mode": "enhanced_dimensions",
  "header_dimensions": {
    "DEPARTMENT": {
      "erp_dimension_id": "DEPT-FOH",
      "source": "mapping_rule",
      "code": "100",
      "name": "Front of House",
      "rule_id": "invmr_98765"
    }
  },
  "vendor_coding": {
    "erp_vendor_id": "SYSCO-001",
    "source": "configured",
    "ottimate_vendor_id": 67890,
    "accounting_class": {
      "erp_dimension_id": "CLASS-VENDOR-DEFAULT",
      "code": "CLASS-VENDOR-DEFAULT",
      "name": "Vendor Default Class",
      "source": "configured"
    },
    "default_department": {
      "erp_dimension_id": "DEPT-KITCHEN",
      "code": "200",
      "name": "Kitchen",
      "source": "configured"
    }
  },
  "all_line_items": [
    {
      "charge_type": null,
      "dimensions": {
        "CLASS": {
          "id": "dim_abc123",
          "erp_dimension_id": "99",
          "name": "General",
          "code": "GEN",
          "display_name": "General (GEN)"
        }
      }
    }
  ],
  "by_item_description": {
    "count": 1,
    "page": 1,
    "limit": 20,
    "results": [
      {
        "item_description": "CHICKEN BREAST 40LB",
        "dimensions": {
          "ACCOUNT": {
            "id": "dim_jkl012",
            "erp_dimension_id": "5100",
            "name": "Poultry",
            "code": "5100",
            "display_name": "Poultry (5100)"
          }
        }
      }
    ]
  },
  "default_gl": null,
  "warnings": []
}
```

**SDK Code**

```python Enhanced Dimensions account with a matching default
import requests

url = "https://api.ottimate.com/v1/coding-defaults"

querystring = {"ottimate_location_id":"12345","erp_vendor_id":"SYSCO-001","applies_to":"header","item_description":"CHICKEN BREAST 40LB","page":"1","limit":"20"}

headers = {
    "X-Api-Key": "your-api-key-here",
    "X-API-Version": "1.0.0",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Enhanced Dimensions account with a matching default
const url = 'https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20';
const options = {
  method: 'GET',
  headers: {
    'X-Api-Key': 'your-api-key-here',
    'X-API-Version': '1.0.0',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Enhanced Dimensions account with a matching default
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "your-api-key-here")
	req.Header.Add("X-API-Version", "1.0.0")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Enhanced Dimensions account with a matching default
require 'uri'
require 'net/http'

url = URI("https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = 'your-api-key-here'
request["X-API-Version"] = '1.0.0'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Enhanced Dimensions account with a matching default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20")
  .header("X-Api-Key", "your-api-key-here")
  .header("X-API-Version", "1.0.0")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Enhanced Dimensions account with a matching default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-API-Version' => '1.0.0',
    'X-Api-Key' => 'your-api-key-here',
  ],
]);

echo $response->getBody();
```

```csharp Enhanced Dimensions account with a matching default
using RestSharp;

var client = new RestClient("https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Api-Key", "your-api-key-here");
request.AddHeader("X-API-Version", "1.0.0");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Enhanced Dimensions account with a matching default
import Foundation

let headers = [
  "X-Api-Key": "your-api-key-here",
  "X-API-Version": "1.0.0",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Legacy GL account

**Response**

```json
{
  "ottimate_location_id": 12345,
  "erp_vendor_id": "SYSCO-001",
  "accounting_mode": "legacy_gl",
  "header_dimensions": {},
  "vendor_coding": {
    "erp_vendor_id": "SYSCO-001",
    "source": "configured",
    "ottimate_vendor_id": 67890,
    "accounting_class": null,
    "default_department": {
      "erp_dimension_id": "DEPT-KITCHEN",
      "code": "200",
      "name": "Kitchen",
      "source": "configured"
    }
  },
  "all_line_items": [],
  "by_item_description": {
    "count": 0,
    "page": 1,
    "limit": 20,
    "results": []
  },
  "default_gl": {
    "erp_dimension_id": "5000",
    "source": "configured",
    "code": "5000",
    "name": "Food Cost"
  },
  "warnings": []
}
```

**SDK Code**

```python Legacy GL account
import requests

url = "https://api.ottimate.com/v1/coding-defaults"

querystring = {"ottimate_location_id":"12345","erp_vendor_id":"SYSCO-001","applies_to":"header","item_description":"CHICKEN BREAST 40LB","page":"1","limit":"20"}

headers = {
    "X-Api-Key": "your-api-key-here",
    "X-API-Version": "1.0.0",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Legacy GL account
const url = 'https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20';
const options = {
  method: 'GET',
  headers: {
    'X-Api-Key': 'your-api-key-here',
    'X-API-Version': '1.0.0',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Legacy GL account
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "your-api-key-here")
	req.Header.Add("X-API-Version", "1.0.0")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Legacy GL account
require 'uri'
require 'net/http'

url = URI("https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = 'your-api-key-here'
request["X-API-Version"] = '1.0.0'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Legacy GL account
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20")
  .header("X-Api-Key", "your-api-key-here")
  .header("X-API-Version", "1.0.0")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Legacy GL account
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-API-Version' => '1.0.0',
    'X-Api-Key' => 'your-api-key-here',
  ],
]);

echo $response->getBody();
```

```csharp Legacy GL account
using RestSharp;

var client = new RestClient("https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Api-Key", "your-api-key-here");
request.AddHeader("X-API-Version", "1.0.0");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Legacy GL account
import Foundation

let headers = [
  "X-Api-Key": "your-api-key-here",
  "X-API-Version": "1.0.0",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.ottimate.com/v1/coding-defaults?ottimate_location_id=12345&erp_vendor_id=SYSCO-001&applies_to=header&item_description=CHICKEN+BREAST+40LB&page=1&limit=20")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```