Preview coding defaults for a location + vendor | Ottimate Developer Documentation

curl -G https://api.ottimate.com/v1/coding-defaults \
     -H "X-Api-Key: your-api-key-here" \
     -H "X-API-Version: 1.0.0" \
     -H "Authorization: Bearer <token>" \
     -d ottimate_location_id=12345 \
     -d erp_vendor_id=SYSCO-001 \
     -d applies_to=header \
     --data-urlencode "item_description=CHICKEN BREAST 40LB" \
     -d page=1 \
     -d limit=20

{
  "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": []
}

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

Authentication

AuthorizationBearer

OAuth2 authentication flows. Auth server URLs will vary by environment

Query parameters

ottimate_location_idintegerRequired

Restaurant/location ID, same value used on invoice create.

erp_vendor_idstringRequired

ERP accounting vendor ID (the accounting_id on the vendor record). Matched case-insensitively.

applies_toenumOptionalDefaults to 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:

item_descriptionstringOptional

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_typeenumOptional

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:

pageintegerOptional>=1Defaults to 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.

limitintegerOptional1-100Defaults to 20

Page size for paginating by_item_description when item_description is not set.

Response

Successful response with coding defaults

ottimate_location_idinteger

The location ID this response was resolved for

erp_vendor_idstring

The ERP vendor ID this response was resolved for

accounting_modeenum

Whether this location uses Enhanced Dimensions or legacy GL accounting

Allowed values:

header_dimensionsmap from strings to objects

Header-level dimension defaults, keyed by dimension type (e.g. ‘DEPARTMENT’, ‘CLASS’). Empty when accounting_mode is legacy_gl or no default applies.

vendor_codingobject

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

all_line_itemslist of objects

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_descriptionobject or list of objects

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_globject or nullOptional

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.

warningslist of stringsOptional

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

403

Forbidden Error

404

Not Found Error

Authentication

Headers

Query parameters

Response

Errors