Business identity (KYC)

Why Tyxter asks for this

Tyxter operates in Brazil, and three of the things it does on your behalf are regulated around the legal entity, not the API key:

• NF-e fiscal notes— Brazilian fiscal invoices legally require the buyer's identity (CNPJ/CPF, legal name, registered address, tax regime).
• Phone provisioning — when Tyxter acquires a Brazilian number for you through Salvy, Anatel-regulated subscriber-identity obligations attach to that number.
• Open Finance payment initiation— production Iniciador connections initiate PIX payments under Tyxter's regulated relationship with Iniciador.

One business_identity record per organization covers all three. It is org-level: every project and environment under the organization shares the same approval.

What requires approval

Exactly two operations check the gate today, and only in production:

• Production Salvy provisioning — provisioning a Tyxter-acquired number with a tx_live_ key (or from the dashboard in a production environment).
• Production Iniciador connection registration — registering an Iniciador payments or agentic-payments connection for a production environment (a dashboard / credential-setup flow).

The gate runs before any state is written: a blocked request commits nothing — no phone number row, no reservation, no charge — so it is safe to repeat the same call after approval.

What is never gated

• Everything in sandbox — provisioning, payments, the whole first-touch integration loop.
• BYON — connecting a number you already own via POST /v1/phone-numbers/connect.
• The Meta connection and messaging through your own WABA — that runs under your own Meta relationship and compliance perimeter.
• Templates, contacts, webhooks, API keys, billing top-ups, Abacate Pay connections.

What we collect

Status lifecycle

not_submitted  →  pending_review  →  approved
                                  →  rejected

• Auto-approval (CNPJ): on submission, Tyxter looks the CNPJ up in the public registry. An active registration whose registered legal name matches your submission approves instantly (verification_source = automated_cnpj_lookup) — the common case never waits for a human.
• Manual review: anything else — name mismatch, inactive registration, registry unavailable, or any CPF submission — stays pending_review for a Tyxter operator. A registry lookup failure never auto-rejects.
• Resubmission: you can resubmit from any state, including approved (to update your data) and rejected (to fix what was wrong). Every resubmission goes back through review.

Error codes

Gated operations return 403 with one of two stable codes (both in the error catalogand on the operation's OpenAPI entry):

kyc_required — no usable identity on file: never submitted, or the last submission was rejected. Submit (or fix and resubmit) in the dashboard.

{
  "error": {
    "type": "authorization_error",
    "code": "kyc_required",
    "message": "Business identity verification is required before this operation. Submit your business identity in the dashboard (Settings → Business identity).",
    "request_id": "req_...",
    "trace_id":   "trc_..."
  }
}

kyc_pending — a submission exists and is awaiting review. Nothing to fix on the request; the operation unlocks on approval.

{
  "error": {
    "type": "authorization_error",
    "code": "kyc_pending",
    "message": "Business identity verification is still in progress. This operation unlocks once the identity is approved.",
    "request_id": "req_...",
    "trace_id":   "trc_..."
  }
}

Where to complete it

In the dashboard: Settings → Business identity. Submitting requires an organization owner or admin role. There is one identity per organization (submissions update it in place), and there is no public /v1KYC endpoint — the dashboard is the only place to submit and the page shows the current status, the verification source, and the reviewer's reason if a submission was rejected.