---
title: "entities.upsert"
method: POST
path: "/capabilities/entities.upsert"
tags: ["Capabilities"]
---

# entities.upsert

`POST /capabilities/entities.upsert`

Create a new business entity or update an existing one.

## Request body

- object
  - `entityId` string — Entity ID to update. Omit to create a new entity.
  - `name` string, required — Business entity name
  - `streetAddress` string — Street address
  - `addressLine2` string — Address line 2
  - `city` string — City
  - `stateOrProvince` string — State or province
  - `postalCode` string — Postal/zip code
  - `country` string, required — Country name
  - `contactNumber` string — Phone number
  - `email` string — Email address
  - `taxId` string — Tax ID / VAT number
  - `chartOfAccountsId` union — Chart of accounts used to categorize this entity's documents. Null clears the assignment.
    - EntityId — unresolved $ref
    - 'default'
  - `aliases` string[] — Alternative names for this entity

## Response `200`

Successful response

- object
  - `success` boolean
  - `code` integer
  - `data` object
    - `result` object — Capability-specific result

## Other responses

- `400` — Invalid input
- `401` — Authentication required
- `404` — Resource not found

---

[API](https://skmtc.net/receiptor/apis/receiptor-ai-api.md) · [All operations](https://skmtc.net/receiptor/apis/receiptor-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/receiptor/receiptor-ai-api/revisions/da17f0eb65a2/schema)