Receta de API: Cómo realizar una verificación completa de KYB en un perfil empresarial
Esta guía recorre el flujo completo de la API para ejecutar la verificación Know Your Business (KYB) utilizando Perfiles de Negocio. Cada paso se basa en el anterior, y se envían callbacks en cada etapa para que puedas seguir el progreso en tiempo real.
URL base: https://api.aiprise.com/api/v1/verify
Autenticación: Todas las solicitudes requieren el x-api-key encabezado.
Diagrama de flujo completo

Resumen
Paso | Punto final | Propósito |
1 |
| Crear la entidad comercial |
2 |
| Ejecutar verificaciones KYB (búsqueda en registro, AML, etc.) |
3a |
| Agregar una persona relacionada (UBO/director) |
3b |
| Ejecutar KYC en la persona relacionada |
3c |
| Generar un enlace de verificación en su lugar |
4a |
| Agregar una empresa relacionada |
4b |
| Ejecutar KYB en la empresa relacionada (usando su ID de perfil comercial) |
5a |
| Cargar un documento empresarial |
5b |
| Ejecutar verificación de documento |
6 |
| Ejecutar puntuación de riesgo / toma de decisiones |
7 |
| Establecer la decisión final (Aprobar/Rechazar/Revisar) |
Paso 1: Crear un perfil empresarial
Cree una entidad empresarial persistente que contendrá todos los datos de verificación, personas relacionadas, empresas y documentos.
POST /api/v1/verify/create_business_profile
Solicitud
{
"name": "Acme Corporación",
"alternate_name": "Acme Corp",
"tax_identification_number": "12-3456789",
"website": "<https://acme.com>",
"country_code": "US",
"state_code": "DE",
"formation_date": "2015-03-15",
"business_entity_id": "your-internal-id-123",
"client_reference_id": "your-internal-tracking-id",
"client_reference_data": {
"internal_case_number": "CASE-2024-001",
"onboarding_source": "partner-api"
},
"addresses": [
{
"address_street_1": "123 Calle Principal",
"address_street_2": "Suite 400",
"address_city": "Wilmington",
"address_state": "DE",
"address_zip_code": "19801",
"address_country": "US"
}
],
"phone_numbers": ["+13025551234"],
"email_addresses": ["compliance@acme.com"],
"tags": ["alto valor", "fintech"]
}
client_reference_id— su ID de referencia interno para rastrear este negocio a través de los sistemasclient_reference_data— metadatos JSON arbitrarios que desea adjuntar a este perfil (se trasladan a todas las sesiones de verificación)
Respuesta
{
"business_profile_id": "bp_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Devolución de llamada
Tipo de evento: BUSINESS_PROFILE_CREATE
{
"callback_event_id": "evt_...",
"event_type": "BUSINESS_PROFILE_CREATE",
"business_profile_id": "bp_a1b2c3d4-..."
}
Guarda el business_profile_id — lo usarás en cada llamada posterior.
Paso 2: Ejecutar la verificación del perfil empresarial
Esto activa el flujo de trabajo KYB configurado en su plantilla (p.ej., búsqueda en el registro, verificación de TIN, filtrado AML, medios adversos).
POST /api/v1/verify/run_verification_for_business_profile_id
Solicitud
{
"business_profile_id": "bp_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"template_id": "your-kyb-template-id"
}
El client_reference_id y client_reference_data establecidos durante la creación del perfil se transfieren automáticamente a la sesión de verificación. No necesitas pasarlos de nuevo.
Respuesta
{
"business_profile_id": "bp_a1b2c3d4-...",
"aiprise_result": {
"verification_session_id": "vs_...",
"business_profile_id": "bp_a1b2c3d4-...",
"business_profile_result": "DESCONOCIDO",
"lookup_info": {
"company_name": "Corporación Acme",
"registration_number": "1234567",
"status": "Activo",
"jurisdiction": "Delaware",
"officers": []
},
"related_persons": [],
"related_companies": [],
"documents": []
}
}
El lookup_info contiene los datos del registro extraídos en tiempo real. También puede devolver oficiales/directores sugeridos del registro que luego puedes agregar como personas relacionadas.
Devolución de llamada
Tipo de evento: RUN_BUSINESS_VERIFICATION
La carga útil de la devolución contiene el resultado completo de la verificación empresarial. Esto se envía a tu events_callback_url.
Además, cuando la sesión de verificación se complete, una VERIFICATION_SESSION_COMPLETION llamada se envía a tu callback_url con los datos completos del perfil empresarial.
Paso 3: Añadir Personas Relacionadas y Ejecutar Verificación
3a. Añadir una Persona Relacionada (UBO / Director / Oficial)
POST /api/v1/verify/related_person_v2
En la API v2, las personas relacionadas están respaldadas por un perfil de usuario completo, lo que permite datos más ricos y jerarquías de entidades de nivel n.
Solicitud
{
"business_profile_id": "bp_a1b2c3d4-...",
"user_profile": {
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-06-15",
"email_address": "jane.doe@acme.com",
"phone_number": "+13025559876",
"address": {
"address_street_1": "456 Oak Ave",
"address_city": "Wilmington",
"address_state": "DE",
"address_zip_code": "19801",
"address_country": "US"
},
"client_reference_id": "your-person-ref-id",
"client_reference_data": {}
},
"ownership_percent": 25.0,
"shares_allocated": 1000,
"roles": ["UBO", "Director"]
}
Respuesta
{
"business_profile_id": "bp_a1b2c3d4-...",
"person_reference_id": "pr_f1e2d3c4-..."
}
Llamada de retorno
Tipo de evento: ADD_BUSINESS_OFFICER — la carga incluye el objeto de persona relacionada completo.
3b. Ejecutar verificación KYC en la persona relacionada
Una vez que se agrega la persona relacionada, realice KYC en su perfil de usuario. El person_reference_id devuelto en el paso 3a corresponde a un perfil de usuario que puede verificar.
POST /api/v1/verify/run_verification_for_user_profile_id
Solicitud
{
"user_profile_id": "pr_f1e2d3c4-...",
"template_id": "your-kyc-template-id",
"user_data": {
"first_name": "Jane",
"last_name": "Doe",
"date_of_birth": "1985-06-15",
"email_address": "jane.doe@acme.com"
},
"additional_info": [
{
"additional_info_type": "PROOF_OF_ADDRESS",
"additional_info_data": "\u003cbase64-encoded-document\u003e"
}
]
}
user_data se pre-poblado a partir del registro de persona relacionado creado en el paso 3a. Los campos que pases aquí sobrescribirán los valores almacenados.
Respuesta
{
"verification_session_id": "vs_...",
"user_profile_id": "pr_f1e2d3c4-...",
"user_profile_result": "UNKNOWN"
}
Llamada de retorno
Tipo de evento: BUSINESS_OFFICER_RUN_KYC — la carga útil incluye el resultado de la verificación KYC más el person_reference_id.
3c. Generar un enlace de verificación (alternativa a incrustado)
Utiliza esto cuando quieras que la persona complete el KYC por sí misma mediante un flujo de verificación alojado.
POST /api/v1/verify/create_verification_session_url_for_user_profile
Solicitud
{
"user_profile_id": "pr_f1e2d3c4-...",
"template_id": "your-kyc-template-id",
"redirect_uri": "\u003chttps://your-app.com/verification-complete\u003e"
}
Campos opcionales: client_reference_id, client_reference_data, theme_options, ui_options.
Respuesta
{
"verification_url": "<https://verify.aiprise.io/session/>..."
}
Comparte esta URL con la persona. Cuando completen el flujo, un BUSINESS_OFFICER_RUN_KYC callback se envía automáticamente.
Llamada de retorno
Tipo de evento: USER_PROFILE_CREATE_SESSION_URL
{
"callback_event_id": "evt_...",
"event_type": "USER_PROFILE_CREATE_SESSION_URL",
"user_profile_id": "pr_f1e2d3c4-...",
"session_url": "\u003chttps://verify.aiprise.io/session/\u003e...",
"verification_session_id": "vs_...",
"expires_at": 1735689600000
}
Paso 4: Añadir Empresas Relacionadas y Ejecutar Verificación
4a. Añadir una Empresa Relacionada
POST /api/v1/verify/related_company_v2
En la API v2, las empresas relacionadas están respaldadas por su propio perfil comercial, lo que permite jerarquías KYB recursivas de varios niveles (p. ej., empresa matriz > subsidiaria > sub-subsidiaria).
Solicitud
{
"business_profile_id": "bp_a1b2c3d4-...",
"relationship_type": "PARENT",
"business_profile": {
"name": "Acme Holdings LLC",
"tax_identification_number": "98-7654321",
"country_code": "US",
"state_code": "DE",
"addresses": [
{
"address_street_1": "789 Corporate Blvd",
"address_city": "Dover",
"address_state": "DE",
"address_zip_code": "19901",
"address_country": "US"
}
],
"client_reference_id": "your-company-ref-id",
"client_reference_data": {}
},
"ownership_percent": 100.0,
"shares_allocated": 5000,
"roles": ["Parent Company"]
}
Respuesta
{
"business_profile_id": "bp_a1b2c3d4-...",
"company_reference_id": "cr_g7h8i9j0-..."
}
Llamada de retorno
Tipo de evento: ADD_RELATED_COMPANY — la carga útil incluye el objeto completo de la empresa relacionada.
4b. Ejecutar KYB en la empresa relacionada
Dado que las empresas relacionadas con v2 están respaldadas por su propio perfil comercial, ejecutas la verificación usando el mismo endpoint que el Paso 2 — simplemente pasa la empresa relacionada company_reference_id (que es su propio ID de perfil comercial).
POST /api/v1/verify/run_verification_for_business_profile_id
Solicitud
{
"business_profile_id": "cr_g7h8i9j0-...",
"template_id": "your-kyb-template-id"
}
El company_reference_id devuelto en el paso 4a es un ID de perfil empresarial. Pásalo directamente como business_profile_id aquí. Los datos de la empresa relacionada (nombre, NIT, dirección, etc.) ya se establecieron cuando la creaste en el paso 4a.
Respuesta
{
"business_profile_id": "cr_g7h8i9j0-...",
"aiprise_result": {
"verification_session_id": "vs_...",
"business_profile_id": "cr_g7h8i9j0-...",
"business_profile_result": "UNKNOWN",
"lookup_info": {}
}
}
Llamada de retorno
Tipo de evento: RUN_BUSINESS_VERIFICATION — misma estructura de devolución de llamada que el Paso 2, limitada al perfil comercial de la empresa relacionada.
Paso 5: Cargar y Verificar Documentos Comerciales
5a. Subir un documento
POST /api/v1/verify/add_business_document
Solicitud
{
"business_profile_id": "bp_a1b2c3d4-...",
"file_name": "certificate_of_incorporation.pdf",
"file_type": "CERTIFICATE_OF_INCORPORATION",
"file_blob": "<base64-encoded-file>"
}
Tamaño máximo de archivo: 50 MB. Formatos compatibles: PDF, PNG, JPG, JPEG.
Respuesta
{
"file_uuid": "file_k1l2m3n4-..."
}
Llamada de retorno
Tipo de evento: ADD_ADDITIONAL_MEDIA
5b. Ejecutar una verificación del documento
POST /api/v1/verify/run_check_on_business_document
Solicitud
{
"business_profile_id": "bp_a1b2c3d4-...",
"template_id": "your-document-check-template-id",
"file_uuid": "file_k1l2m3n4-...",
"document_input_title": "Certificate of Incorporation"
}
Respuesta
La respuesta contiene los resultados de la verificación del documento, incluyendo la extracción OCR, la detección de manipulación y cualquier verificación de documentos configurada.
{
"verification_session_id": "vs_...",
"document_check_result": {}
}
Llamada de retorno
Tipo de evento: RUN_BUSINESS_DOCUMENT_CHECK
Paso 6: Ejecutar puntuación de riesgo / toma de decisiones
La puntuación de riesgo utiliza el mismo endpoint que la toma de decisiones, pero con un ID de plantilla de puntuación de riesgo en lugar de una plantilla KYB regular. La plantilla de puntuación de riesgo agrega resultados de todos los pasos anteriores (datos del registro, resultados de KYC de UBO, verificaciones de documentos, etc.) y produce una puntuación de riesgo.
POST /api/v1/verify/make_decision_with_risk_scoring
Solicitud
{
"business_profile_id": "bp_a1b2c3d4-...",
"template_id": "your-risk-scoring-template-id"
}
El template_id aquí debe ser una plantilla configurada como una plantilla de puntuación de riesgo o de toma de decisiones. Esta es una plantilla diferente de la utilizada en el Paso 2.
Respuesta
{
"verification_session_id": "vs_...",
"business_profile_id": "bp_a1b2c3d4-..."
}
Devolución de llamada
Tipo de evento: RUN_RISK_SCORING (para plantillas de puntuación de riesgo) o MAKE_DECISION (para plantillas de decisión)
La puntuación de riesgo/toma de decisiones requiere que todas las sesiones hijas (UBO KYC, KYB de la empresa relacionada, verificaciones de documentos) se hayan completado. Si alguna sesión hija aún está pendiente, el flujo de trabajo de puntuación de riesgo no tendrá todos los datos para trabajar.
Paso 7 (Opcional): Establecer manualmente la decisión final
Si deseas sobrescribir o establecer manualmente el resultado del perfil empresarial:
POST /api/v1/verify/update_business_profile_result
Solicitud
{
"business_profile_id": "bp_a1b2c3d4-...",
"result": "APPROVED"
}
Valores válidos para result: APPROVED, DECLINED, REVIEW, DEACTIVATED
Si está configurando DECLINED como valor, reason_code es obligatorio.
Devolución de llamada
Tipo de evento: RESULT_UPDATE
El perfil completo del negocio se envía a su callback_url, y una actualización incremental del evento se envía a su events_callback_url.
Referencia de callbacks
Configuración
Las URL de Callback se configuran en tu plantilla en el panel de AiPrise:
callback_url— recibe la carga completa del perfil empresarial cuando se completa una sesión de verificación (VERIFICATION_SESSION_COMPLETION)events_callback_url— recibe actualizaciones incrementales de eventos a medida que cada acción ocurre en el perfil empresarial
Seguridad
Todas las llamadas de retorno incluyen una firma HMAC-SHA256 en el X-HMAC-SIGNATURE encabezado, calculada a partir de la carga útil usando la clave secreta de su empresa. Siempre valide esta firma antes de procesarla.
Tipos de Evento
Evento | Disparador |
| Perfil de negocio creado |
| Verificación KYB ejecutada en el negocio |
| Persona relacionada añadida |
| Persona relacionada actualizada |
| Persona relacionada eliminada |
| Verificación KYC realizada en una persona relacionada |
| Enlace de verificación generado para una persona relacionada |
| Empresa relacionada añadida |
| Empresa relacionada actualizada |
| Empresa relacionada eliminada |
| Verificación KYB realizada en una empresa relacionada |
| Documento de negocio cargado |
| Documento de negocio actualizado |
| Documento de negocio eliminado |
| Revisión de documento ejecutada |
| Puntuación de riesgo ejecutada |
| Decisión ejecutada |
| Resultado del perfil de negocio actualizado manualmente |
| Solicitud de verificación enviada mediante invitación por correo electrónico |
| Información del perfil de negocio actualizada |
Estructura del Payload de Callback
Todas las devoluciones de llamada de eventos siguen esta estructura:
{
"callback_event_id": "unique-event-id",
"event_type": "EVENT_TYPE",
"business_profile_id": "bp_...",
"verification_session_id": "vs_... (when applicable)",
"target_id": "person or company reference ID (when applicable)"
}
Reintentos
Las devoluciones de llamada se entregan de forma asíncrona. Si su endpoint devuelve una respuesta que no sea 2xx, la devolución de llamada se reintentará automáticamente.
