Create an expense category

Operation ID: createExpenseCategory

Group: Accounting › Expense Categories

Open in the interactive reference

POST /accounting/expense-categories

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates an expense category. The category is available in the legal entities in entityIds, and journal entries for its expense items use the general ledger accounts in accountIds. The response contains only its id.

The name must be unique within the tenant. A reimbursable category must have at least one account in accountIds. At most one active distance ('Dis') category can exist for each reimbursable value, one reimbursable and one not.

Every account in accountIds must have an account subtype that is enabled for expense reports. Otherwise the request fails with an error that has no code in the error list.

Read the new record with GET accounting/expense-categories/:id.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: createExpenseCategoryInput.

Field Type Required Description
category string yes The name of the expense category, for example 'Client Entertainment'. Must be unique across the tenant. Example: "Client Entertainment".
categoryType string no The kind of expense. Accepted values: 'Pur', 'Dis', 'PerDiem'. 'Dis' is distance traveled. Omit to leave it unset. Example: "Pur".
status string no The lifecycle status. Accepted values: 'active', 'inactive'. Defaults to 'active'.
reimbursable boolean no Whether expenses in this category are reimbursed to the employee. Defaults to true. A reimbursable category must have at least one accountId. Example: true.
requireAttachment boolean no Whether an expense in this category must have a receipt attachment. Example: true.
requireAttendees boolean no Whether an expense in this category must list attendees.
entityIds array<string> no The legal entities this category is available in. This array replaces the whole set. Omit to leave it unchanged. Send an empty array to remove every entity. See id on GET base/entities.
accountIds array<string> no The general ledger accounts that journal entries for this category's expense items use. This array replaces the whole set. Required unless the category is not reimbursable. See id on GET accounting/accounts/:id. Example: ["7c1a9e40-2b53-4d68-9f01-3a5b7c9d1e24"]. 
{
  "category": "Client Entertainment",
  "categoryType": "Pur",
  "status": "<status>",
  "reimbursable": true,
  "requireAttachment": true,
  "requireAttendees": true,
  "entityIds": [
    "<entityIds>"
  ],
  "accountIds": [
    "7c1a9e40-2b53-4d68-9f01-3a5b7c9d1e24"
  ]
}

Response

200 Success

Under data (createExpenseCategoryOutput):

Field Type Required Description
id string yes The unique identifier for the created expense category. Example: "b81f4a22-6d90-4c53-8e17-9f2a4b6c8d05". 
{
  "data": {
    "id": "b81f4a22-6d90-4c53-8e17-9f2a4b6c8d05"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
DUPLICATE_CATEGORY 400
DUPLICATE_DISTANCE_CATEGORY 400
NO_ACCOUNT_SELECTED 400
REFERENCE_NOT_FOUND 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses