---
title: "Create entity"
method: POST
path: "/entities"
tags: ["Entities"]
---

# Create entity

`POST /entities`

Creates an entity in your organization for the mode (`live` or `test`) of the API key used. An entity is a legal holder of accounts. Returns the created entity.

## Request body

- object
  - `country_code` string, required — ISO 3166-1 alpha-2 country code of the entity. Use `MX` for a Mexican entity, or another code such as `US` for a foreign entity.
  - `holder_name` string, required — Legal name of the entity owner.
  - `holder_id` string — Mexican tax ID (RFC) of the entity owner, without dots or hyphens. Required for a Mexican entity (`country_code` is `MX`). For a foreign entity, omit this field or send the generic foreign RFC `XEXX010101000`; Fintoc rejects any other value. Must be unique within your organization, except the generic foreign RFC `XEXX010101000`, which can repeat across foreign entities.

## Response `201`

The created entity.

- Entity
  - `id` string, required — Unique identifier of the entity.
  - `object` 'entity', required — Type of the object. Always `entity`.
  - `country_code` string, nullable, required — ISO 3166-1 alpha-2 country code of the entity, in lowercase, or `null` when not set. For example, `cl` or `mx`.
  - `holder_id` string, required — Mexican tax ID (RFC) of the entity owner, without dots or hyphens. For a foreign entity, the value is the generic foreign RFC `XEXX010101000`.
  - `holder_name` string, required — Legal name of the entity owner.
  - `is_root` boolean, required — Whether this entity is your organization's root entity.
  - `mode` 'live' | 'test', required — Whether the entity belongs to `live` or `test` data. One of `live` or `test`.
  - `status` 'draft' | 'under_review' | 'pending_signature' | 'canceled' | 'waiting_initialization' | 'operational' | 'rejected' | 'paused', required — Current status of the entity. One of `draft`, `under_review`, `pending_signature`, `canceled`, `waiting_initialization`, `operational`, `rejected`, or `paused`.

## Other responses

- `400` — Invalid request: a body parameter is missing or invalid.
- `401` — Invalid or missing API key.
- `409` — An entity with the same `holder_id` already exists in your organization. The generic foreign RFC `XEXX010101000` is exempt and can repeat.

---

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