> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capcells.com/llms.txt
> Use this file to discover all available pages before exploring further.

# State the company profile

> Record what your Tenancy says about the company behind it, and receive the profile back with the moment it was recorded.

A Company profile is what your Tenancy says about the company behind it: the legal entity, the market, its time zone, and optionally a brand name and a legal form. This call records it whole and answers `200` with the profile as recorded.

A Tenancy holds one profile. This call is both the first statement and every correction after it: onboarding and a later correction are the same act performed at different times, so both answer `200` and a caller cannot tell them apart by status. A statement replaces what the last one said, and no call answers what it replaced.

<Info>
  The body is read whole. A field you leave out is you saying the company has none, and there is no partial edit — a `PATCH` would have to answer whether an absent brand means keep or clear, and this call never has to.
</Info>

## Path parameters

<ParamField path="tenant_id" type="string" required>
  The Tenancy the profile belongs to. 1–64 characters of `a–z A–Z 0–9 - _`. A key authenticates for one Tenancy and the path names it; another Tenancy's path answers `403`.
</ParamField>

## Body

<ParamField body="legal_entity_name" type="string" required>
  The company as its own registry of companies has it. 1 to 200 characters. Stated as `""` or `null` it is refused `422`, the same as leaving it out.
</ParamField>

<ParamField body="country_code" type="string" required>
  Where the company lends, as an ISO 3166-1 alpha-2 code. One of the 50 countries the Platform names; anything else is refused `422` naming the country. It is not the jurisdiction of any Loan — that is stated per Loan and gates issuance on its own.
</ParamField>

<ParamField body="vat_rate_bps" type="integer" deprecated>
  **Retired — leave it out.** The profile no longer holds a rate: a Loan's tax is one of the rules its jurisdiction admits, stated in the Loan's `tax`. Until **15 January 2027** a statement carrying this field is accepted with the field ignored, whatever it holds, and the answer carries `Deprecation: @1799971200`, `Sunset: Fri, 15 Jan 2027 00:00:00 GMT` and a `Link` to the [changelog entry](/changelog#2026-10-15). From that day it is refused `400` naming the field.
</ParamField>

<ParamField body="time_zone" type="string" required>
  The company's own civil clock, as an IANA zone name — `America/Mexico_City`, not an offset. Required: which day a moment falls on for this company is not something the Platform assumes, and every Decision and Facility is refused until a zone stands.

  The [Console](https://app.capcells.com) prefills it from the country registry entry's `suggested_time_zone` and you confirm or change it. A country is not a zone — Mexico spans three — so the Platform never writes one on your behalf, and what a record freezes is the value you stated and never the suggestion. Absent or blank is refused `422 invalid_statement`; a name the zone database does not carry is refused `422 invalid_time_zone`.
</ParamField>

<ParamField body="brand_name" type="string">
  The name the products go out under, where it differs from the legal one. 1 to 200 characters. Leave the field out when the company trades under its own name: `""` and `null` are refused `422`, because a brand present with no value and a company that states no brand would otherwise be the same statement, and the second is the ordinary case.
</ParamField>

<ParamField body="entity_type" type="string">
  The legal form the company is registered under, named as its own country names it. 1 to 200 characters, and held against no list: the Platform offers legal forms per market and refuses none. Left out, absent, the same way `brand_name` is.
</ParamField>

## Response

<ResponseField name="legal_entity_name" type="string" required>
  As stated.
</ResponseField>

<ResponseField name="country_code" type="string" required>
  As stated.
</ResponseField>

<ResponseField name="brand_name" type="string">
  As stated, and absent from the answer when the statement made none rather than answered as an empty string.
</ResponseField>

<ResponseField name="entity_type" type="string">
  As stated, and absent the same way.
</ResponseField>

<ResponseField name="time_zone" type="string">
  As stated. Omitted only on a profile stated before this field existed — never a zone the Platform chose. State the profile again to give it one.
</ResponseField>

<ResponseField name="stated_at" type="string" required>
  RFC 3339 in UTC: the moment the Platform recorded the statement. Restating a profile you already hold records nothing and answers the moment that stands, so a retry after a lost response carries the same `stated_at` as the attempt it repeats.
</ResponseField>

## Refusals

Each refusal names the field or the value it is about in `error`, and the kind of refusal in `code`.

| Status | When |
| - | - |
| `400` | The body names a field the profile does not hold, states one key twice, or cannot be read as JSON |
| `403` | The key is read-scoped, or authenticates for another Tenancy |
| `409` | Two statements claimed the same instant; nothing was written and the statement may be sent again |
| `415` | The body declares no content type, or one other than `application/json` |
| `422` | A required field is missing or empty, an optional field is blank, or the country is one the Platform does not name |
| `422` | `invalid_time_zone`: a zone was stated and the database does not carry it, or it names the machine's own zone rather than a place a company is. A zone left out entirely is the ordinary missing-field refusal above |

<RequestExample>
  ```bash State theme={null}
  BODY='{
    "legal_entity_name": "Capyplazo S.A. de C.V.",
    "brand_name": "Capyplazo",
    "country_code": "MX",
    "entity_type": "S.A. de C.V.",
    "time_zone": "America/Mexico_City"
  }'

  curl -X PUT https://api.capcells.com/v1/tenants/capyplazo/company-profile \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" PUT /v1/tenants/capyplazo/company-profile "$BODY")" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```

  ```json Required fields only theme={null}
  {
    "legal_entity_name": "Capyplazo S.A. de C.V.",
    "country_code": "MX",
    "time_zone": "America/Mexico_City"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "legal_entity_name": "Capyplazo S.A. de C.V.",
    "brand_name": "Capyplazo",
    "country_code": "MX",
    "entity_type": "S.A. de C.V.",
    "time_zone": "America/Mexico_City",
    "stated_at": "2026-08-23T21:27:59.672084Z"
  }
  ```

  ```json 200 Required fields only theme={null}
  {
    "legal_entity_name": "Capyplazo S.A. de C.V.",
    "country_code": "MX",
    "time_zone": "America/Mexico_City",
    "stated_at": "2026-08-23T21:27:59.669329Z"
  }
  ```

  ```json 422 Unknown country theme={null}
  {
    "error": "company: unknown country: the registry does not name JP",
    "code": "unknown_country"
  }
  ```

  ```json 422 Blank optional field theme={null}
  {
    "error": "company: invalid statement: the body states a brand name with nothing in it, and a profile that carries no brand name states none",
    "code": "invalid_statement"
  }
  ```

  ```json 400 Field the profile does not hold theme={null}
  {
    "error": "reading the request: json: unknown field \"tax_id\"",
    "code": "malformed_request"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.