> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API para crear empresas: entidad KYB de proveedor > Crea entidades de empresa (KYB) en Didit antes de sus sesiones. Impórtalas en bloque desde otras bases o regístralas para monitorizar transacciones. Prompt para crear una empresa Copiar el prompt al portapapeles \

\`Goal: Pre-create a Didit Business (KYB) entity by vendor_data before any KYB session runs.

Endpoint: POST https://verification.didit.me/v3/businesses/create/
Auth header: x-api-key: 
Content-Type: application/json

Request body fields:
\- vendor_data (string, REQUIRED) — your unique identifier. Free-form string, NOT a UUID. Must be unique among non-deleted businesses for the app. Normalised lowercase + whitespace trim ("COMPANY-1" and "company-1" collide).
\- display_name (string, nullable) — friendly display name shown in Console (takes precedence over legal_name).
\- legal_name (string, nullable)
\- registration_number (string, nullable)
\- country_code (string, nullable) — country of incorporation, ISO 3166-1 alpha-2 (e.g. "GB", "US").
\- region (string, nullable) — ISO 3166-2 subdivision code.
\- status (enum) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorBusinessStatusChoices). Defaults to "ACTIVE".
\- metadata (object, nullable) — arbitrary JSON.

curl:
curl -X POST 'https://verification.didit.me/v3/businesses/create/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US"}'

Response 201: full BusinessDetailItem (same shape as GET /v3/businesses/{vendor_data}/). Includes didit_internal_id (UUID), session_count=0, metadata, comments=[], created_at, updated_at. See /reference/data-models.

Failure modes (envelope {"detail": "..."} for auth):
\- 400 — validation errors keyed by field. Common cases:
\{ "vendor_data": ["A business with this vendor_data already exists."] }  // NOT idempotent — use PATCH /v3/businesses/{vendor_data}/ to update.
\{ "vendor_data": ["This field is required."] }
\{ "metadata": ["Metadata must be a JSON object."] }
\- 401 — missing/invalid x-api-key.
\- 403 — lacks create:businesses.
\- 429 — rate-limited.

Upsert pattern (NOT idempotent on vendor_data):
GET /v3/businesses/{vendor_data}/  → on 404, POST /v3/businesses/create/; on 200, PATCH /v3/businesses/{vendor_data}/.

Notes:
\- Registry-derived fields (legal_name, registration_number, country_code) can be seeded here but will be OVERWRITTEN by the first approved Business Verification (KYB) session's registry data.
\- last_activity_at is set at the moment of creation.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\
Pegar en ## Descripción generalCrea explícitamente una [entidad empresarial](https://docs.didit.me/es/entities/businesses/overview.md) antes de que se ejecute cualquier sesión de Verificación de empresas (KYB).## Cuándo usarlo- **Precargar metadatos** (socio, nivel, identificadores internos) antes de la primera sesión de Verificación de empresas (KYB). - **Migrar** desde otro proveedor de KYB con una lista de empresas existente. - **Registro solo para transacciones**: enviar transacciones de una empresa que verificaste mediante un proceso fuera de línea.## Notas- `vendor_data` es obligatorio y único por aplicación. Los duplicados devuelven un error de conflicto: usa [`PATCH /v3/businesses/{vendor_data}/`](https://docs.didit.me/es/management-api/businesses/update) para actualizar. - Los campos derivados del registro (`legal_name`, `registration_number`, `country_code`) se pueden precargar, pero los datos del registro de la primera sesión de Verificación de empresas (KYB) aprobada los **sobrescribirán**. - Si `country_code` coincide con la lista de [países peligrosos](https://docs.didit.me/es/entities/businesses/blocklist.md#países-peligrosos) de tu aplicación, la empresa se crea con el estado `BLOCKED`. - Emite `business.data.updated`.## PermisosEl rol debe otorgar `create:businesses`.## Relacionado- [Modelo de datos de empresa](https://docs.didit.me/es/entities/businesses/data-model.md) - [Vinculación de datos de proveedores](https://docs.didit.me/es/entities/vendor-data-linking.md) - [Operaciones empresariales](https://docs.didit.me/es/entities/businesses/operations.md) ## OpenAPI ````yaml es/openapi-25.json POST /v3/businesses/create/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificación de identidad. Autentícate con el encabezado x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/businesses/create/: post: tags: - Businesses summary: Crear empresa description: >- Crea previamente una [empresa](/entities/businesses) *sin* una sesión de KYB. Todos los campos son opcionales, pero siempre deberías enviar `vendor_data`: sin él, el registro no se puede vincular a sesiones ni a transacciones. Cuando se proporciona, `vendor_data` debe ser único entre las empresas no eliminadas (coincidencia exacta; los conflictos devuelven 400). No es idempotente. operationId: create_business requestBody: required: true content: application/json: schema: type: object properties: vendor_data: type: string nullable: true description: >- Tu identificador único de esta empresa (cadena de texto libre, NO un UUID). Es opcional, pero muy recomendable. Si lo indicas, debe ser único entre las empresas no eliminadas de la aplicación; se compara exactamente tal como se envía. display_name: type: string nullable: true maxLength: 255 description: >- Nombre visible descriptivo que se muestra en la consola (tiene prioridad sobre `legal_name` en la interfaz). legal_name: type: string nullable: true maxLength: 255 description: Razón social oficial de la empresa. registration_number: type: string nullable: true maxLength: 100 description: Número de registro o de constitución de la empresa. country_code: type: string nullable: true maxLength: 10 description: >- País de constitución (ISO 3166-1 alfa-2, p. ej., `GB`, `US`). status: type: string enum: - ACTIVE - FLAGGED - BLOCKED default: ACTIVE description: >- Estado inicial del ciclo de vida. El valor predeterminado es `ACTIVE`. metadata: type: object nullable: true description: >- Objeto JSON arbitrario que adjuntas a la empresa. Por defecto es `{}`. examples: Basic: summary: Mínimo recomendado value: vendor_data: company-456 legal_name: New Corp Ltd country_code: US Full: summary: Todos los campos value: vendor_data: company-789 display_name: New Corp legal_name: New Corp International Ltd registration_number: '98765432' country_code: DE status: ACTIVE metadata: industry: fintech tier: enterprise responses: '201': description: >- Empresa creada. Se devuelve el registro completo de la empresa (con la misma estructura que Get Business). content: application/json: schema: $ref: '#/components/schemas/BusinessDetailItem' examples: Created: value: didit_internal_id: a1b2c3d4-e5f6-4890-abcd-ef1234567890 vendor_data: company-456 display_name: null legal_name: New Corp Ltd registration_number: null country_code: US effective_name: New Corp Ltd status: ACTIVE session_count: 0 approved_count: 0 declined_count: 0 in_review_count: 0 features: {} features_list: [] last_session_at: null last_activity_at: '2026-03-15T10:30:00Z' first_session_at: null tags: [] created_at: '2026-03-15T10:30:00Z' metadata: {} updated_at: '2026-03-15T10:30:00Z' '400': description: >- Cuerpo no válido: normalmente un `vendor_data` duplicado, un `status` desconocido o un `metadata` con formato incorrecto. content: application/json: examples: Duplicate: value: vendor_data: - A business with this vendor_data already exists. Bad status: value: status: - >- Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED Bad metadata: value: metadata: - Metadata must be a JSON object. '403': description: >- Clave de API ausente, no válida o revocada, o la clave no puede crear empresas para esta aplicación. Si falta la clave, se devuelve `403`; si la clave es incorrecta, está revocada o ha expirado, se devuelve `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: >- Límite de solicitudes superado; espera y reintenta cuando haya pasado el intervalo indicado en `Retry-After`. content: application/json: examples: Rate limited: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST 'https://verification.didit.me/v3/businesses/create/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US"}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.businesses.create( vendor_data="company-456", legal_name="New Corp Ltd", country_code="US", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.businesses.create({ vendor_data: "company-456", legal_name: "New Corp Ltd", country_code: "US", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Create(ctx, didit.BusinessesCreateParams{\n\tVendorData: didit.String(\"company-456\"),\n\tLegalName: didit.String(\"New Corp Ltd\"),\n\tCountryCode: didit.String(\"US\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.BusinessesCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.businesses().create(BusinessesCreateParams.builder() .vendorData("company-456") .legalName("New Corp Ltd") .countryCode("US") .build()); System.out.println(result); - lang: php label: PHP source: |- businesses->create([ 'vendor_data' => 'company-456', 'legal_name' => 'New Corp Ltd', 'country_code' => 'US', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.businesses.create( vendor_data: "company-456", legal_name: "New Corp Ltd", country_code: "US" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Businesses.CreateAsync(new BusinessesCreateParams { VendorData = "company-456", LegalName = "New Corp Ltd", CountryCode = "US", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: BusinessDetailItem: type: object description: >- Detalle completo de la empresa. Amplía BusinessListItem con los metadatos y updated_at. allOf: - $ref: '#/components/schemas/BusinessListItem' - type: object properties: metadata: type: object description: >- JSON de metadatos personalizados que adjuntaste a esta empresa. Valor predeterminado: `{}`. updated_at: type: string format: date-time BusinessListItem: type: object description: Una empresa verificada. properties: didit_internal_id: type: string format: uuid description: UUID interno estable de Didit para esta empresa. vendor_data: type: string nullable: true description: >- Tu identificador único de esta empresa (el que se envía al crear sesiones). Puede ser null si no se proporcionó ningún identificador propio. display_name: type: string nullable: true description: Nombre visible personalizado que has definido legal_name: type: string nullable: true description: Razón social oficial obtenida del registro o introducida manualmente registration_number: type: string nullable: true description: Número de registro o de constitución de la empresa country_code: type: string nullable: true description: País de constitución (ISO 3166-1 alfa-2, p. ej., `GB`, `US`). effective_name: type: string nullable: true description: >- Mejor nombre disponible: display_name si está definido; si no, legal_name status: type: string enum: - ACTIVE - FLAGGED - BLOCKED description: >- Estado del ciclo de vida del registro de la empresa (NO es un estado de sesión). `ACTIVE` es el valor predeterminado, `FLAGGED` lo marca para atención manual y `BLOCKED` impide nuevas sesiones para este `vendor_data`. session_count: type: integer description: Número total de sesiones de verificación de esta empresa approved_count: type: integer description: Número de sesiones aprobadas declined_count: type: integer description: Número de sesiones rechazadas in_review_count: type: integer description: Número de sesiones en revisión features: type: object description: >- Estado agregado por función de todas las sesiones KYB de esta empresa. Actualmente la única clave es `KYB` (el estado de la comprobación de la empresa en el registro). Valores posibles: `Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`. features_list: type: array items: type: object properties: feature: type: string status: type: string description: >- Los mismos datos que `features`, como un array ordenado de objetos `{feature, status}`. last_session_at: type: string format: date-time nullable: true description: Marca de tiempo de la sesión más reciente first_session_at: type: string format: date-time nullable: true description: Marca de tiempo de la primera sesión last_activity_at: type: string format: date-time nullable: true description: >- Marca de tiempo de la actividad más reciente (cambio de estado, actualización de la sesión, etc.) tags: type: array items: type: object properties: uuid: type: string format: uuid name: type: string color: type: string description: Etiquetas asignadas a esta empresa created_at: type: string format: date-time securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.