Resultados

Consulta, aprueba o rechaza resultados de verificación KYC y KYB, gestiona warnings por step, edita campos y agrega comentarios de auditoría

Listar resultados KYC

GET

https://api-id-dev.adamoservices.co/api/v1

/results/kyc

Obtiene una lista paginada de resultados de verificación KYC con datos resumidos.

Permiso requerido: adamo_id:verifications:list:read

Listar resultados KYC › query Parameters

page

integer

Número de página

Default: 1

limit

integer

Cantidad de resultados por página

Default: 10

organizationId

string · uuid

Filtrar por organización

status

string · enum

Filtrar por estado

Enum values:

in_progress

completed

abandoned

expired

saved_for_later

startDate

string · date

Fecha inicial (YYYY-MM-DD)

endDate

string · date

Fecha final (YYYY-MM-DD)

searchTerm

string

Buscar por nombre o email

Listar resultados KYC › Responses

Lista de resultados KYC

success

boolean

KycResultListItem[]

object

GET/results/kyc

curl https://api-id-dev.adamoservices.co/api/v1/results/kyc \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "flowRunUuid": "7d2370ca-09c0-4026-a1b4-d7bf20bf89f6",
      "date": "2026-06-01T10:00:00Z",
      "completedDate": "2026-06-01T10:45:00Z",
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "documentId": "12345678",
      "documentType": "dni",
      "verifications": [
        {
          "type": "id_document",
          "stepKey": "id-document-verification",
          "status": "completed",
          "providers": [
            {
              "name": "adamo-id-ocr-ms",
              "status": "completed",
              "passed": true
            }
          ]
        }
      ],
      "totalSteps": 5,
      "ipAddress": "192.168.1.100",
      "status": "completed",
      "result": "approved",
      "riskLevel": "low"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}

json

application/json

Obtener detalle de resultado KYC

GET

https://api-id-dev.adamoservices.co/api/v1

/results/kyc/{uuid}

Obtiene toda la información capturada en un proceso de verificación KYC específico, incluyendo datos del documento, resultados de liveness, facial, etc.

Permiso requerido: adamo_id:evidence:read

Obtener detalle de resultado KYC › path Parameters

uuid

string · uuid · required

UUID del resultado KYC

Obtener detalle de resultado KYC › Responses

Detalle completo del resultado KYC

success

boolean

data

object

Objeto FlowRunResult completo con toda la información capturada

Editar datos del documento de identidad KYC

PATCH

https://api-id-dev.adamoservices.co/api/v1

/results/kyc/{uuid}

Permite editar manualmente cualquier campo de capturedData.documentInfo de un flow run KYC (id-document-verification step).

Permiso requerido: adamo_id:evidence:read

Campos editables:

Campos de configuración (selectedCountry, selectedDocument, authenticityScore)
Datos confirmados (confirmedData)
Datos extraídos (extractedData)

Características:

Actualización parcial (solo los campos enviados se modifican)
Establece hasManualChanges: true automáticamente
Valida pertenencia a la organización (multi-tenant)
Registra cambios en changeHistory con metadata de auditoría

Editar datos del documento de identidad KYC › path Parameters

uuid

string · uuid · required

UUID del flow run result a editar

Editar datos del documento de identidad KYC › Request Body

object · required

Campos del documento a actualizar (actualización parcial)

changeReason

string · maxLength: 500

Razón del cambio (para auditoría)

Example: Corrección manual por error de OCR

Editar datos del documento de identidad KYC › Responses

Datos actualizados exitosamente

success

boolean

message

string

object

PATCH/results/kyc/{uuid}

curl https://api-id-dev.adamoservices.co/api/v1/results/kyc/:uuid \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "documentInfo": {
    "selectedDocument": "passport"
  },
  "changeReason": "Usuario seleccionó documento incorrecto"
}'

Example Request Body

{
  "documentInfo": {
    "selectedDocument": "passport"
  },
  "changeReason": "Usuario seleccionó documento incorrecto"
}

json

application/json

Example Responses

{
  "success": true,
  "message": "Flow run data updated successfully",
  "data": {
    "flowRunUuid": "57f0547b-ecbd-433d-9fe8-86fefdf9c362",
    "changeId": "ff6130d3-78f2-4443-bf7d-eb78fe94bd45",
    "updatedFields": [
      "selectedDocument",
      "confirmedData.firstName",
      "confirmedData.lastName"
    ],
    "changedAt": "2026-02-06T10:30:00.000Z"
  }
}

json

application/json

Aprobar resultado KYC

POST

https://api-id-dev.adamoservices.co/api/v1

/results/kyc/{uuid}/approve

Aprueba un resultado de verificación KYC completado y envía notificación por correo al destinatario.

Permiso requerido: adamo_id:risk_alerts:resolve

Aprobar resultado KYC › path Parameters

uuid

string · uuid · required

UUID del resultado KYC a aprobar

Aprobar resultado KYC › Request Body

ApproveResultRequest

approvedBy

string · minLength: 2 · required

Usuario/revisor que aprueba (mínimo 2 caracteres)

Example: Juan Pérez - Oficial de Compliance

comments

string

Comentarios adicionales opcionales

Example: Documentación completa y verificada correctamente

riskLevel

string · enum

Nivel de riesgo asignado

Enum values:

low

medium

high

critical

Example: low

score

number · min: 0 · max: 100

Score de evaluación (0-100)

Example: 95

sendNotification

boolean

Enviar notificación por correo (default true)

Default: true

Aprobar resultado KYC › Responses

Resultado aprobado exitosamente

ResultDecisionResponse

success

boolean

message

string

object

POST/results/kyc/{uuid}/approve

curl https://api-id-dev.adamoservices.co/api/v1/results/kyc/:uuid/approve \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "approvedBy": "Juan Pérez - Oficial de Compliance",
  "comments": "Documentación completa y verificada correctamente",
  "riskLevel": "low",
  "score": 95,
  "sendNotification": true
}'

Example Request Body

{
  "approvedBy": "Juan Pérez - Oficial de Compliance",
  "comments": "Documentación completa y verificada correctamente",
  "riskLevel": "low",
  "score": 95,
  "sendNotification": true
}

json

Example Responses

{
  "success": true,
  "message": "Resultado aprobado exitosamente",
  "data": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "flowRunUuid": "00000000-0000-0000-0000-000000000000",
    "flowType": "kyc",
    "overallStatus": "approved",
    "finalRiskLevel": "low",
    "finalScore": 95,
    "approvedAt": "2024-08-25T15:00:00Z",
    "approvedBy": "approvedBy",
    "rejectedAt": "2024-08-25T15:00:00Z",
    "rejectedBy": "rejectedBy",
    "emailSent": true
  }
}

json

application/json

Rechazar resultado KYC

POST

https://api-id-dev.adamoservices.co/api/v1

/results/kyc/{uuid}/reject

Rechaza un resultado de verificación KYC completado y envía notificación por correo al destinatario.

Permiso requerido: adamo_id:risk_alerts:resolve

Rechazar resultado KYC › path Parameters

uuid

string · uuid · required

UUID del resultado KYC a rechazar

Rechazar resultado KYC › Request Body

RejectResultRequest

rejectionReason

string · minLength: 10 · required

Razón del rechazo (mínimo 10 caracteres)

Example: Documento de identidad ilegible y no se puede verificar la autenticidad

rejectedBy

string · required

Usuario/revisor que rechaza

Example: Juan Pérez - Analista de Cumplimiento

comments

string

Comentarios adicionales opcionales

Example: Por favor, envíe una imagen más clara del documento

sendNotification

boolean

Enviar notificación por correo (default true)

Default: true

Rechazar resultado KYC › Responses

Resultado rechazado exitosamente

ResultDecisionResponse

success

boolean

message

string

object

POST/results/kyc/{uuid}/reject

curl https://api-id-dev.adamoservices.co/api/v1/results/kyc/:uuid/reject \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "rejectionReason": "Documento de identidad ilegible y no se puede verificar la autenticidad",
  "comments": "Por favor, envíe una imagen más clara del documento",
  "rejectedBy": "Juan Pérez - Analista de Cumplimiento",
  "sendNotification": true
}'

Example Request Body

{
  "rejectionReason": "Documento de identidad ilegible y no se puede verificar la autenticidad",
  "comments": "Por favor, envíe una imagen más clara del documento",
  "rejectedBy": "Juan Pérez - Analista de Cumplimiento",
  "sendNotification": true
}

json

Example Responses

{
  "success": true,
  "message": "Resultado aprobado exitosamente",
  "data": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "flowRunUuid": "00000000-0000-0000-0000-000000000000",
    "flowType": "kyc",
    "overallStatus": "approved",
    "finalRiskLevel": "low",
    "finalScore": 95,
    "approvedAt": "2024-08-25T15:00:00Z",
    "approvedBy": "approvedBy",
    "rejectedAt": "2024-08-25T15:00:00Z",
    "rejectedBy": "rejectedBy",
    "emailSent": true
  }
}

json

application/json

Editar campo de un step del resultado

PATCH

https://api-id-dev.adamoservices.co/api/v1

/results/{uuid}/field

Permite editar un campo específico de un step del resultado, registrando el cambio en el historial de auditoría.

Permiso requerido: adamo_id:evidence:read

Editar campo de un step del resultado › path Parameters

uuid

string · uuid · required

UUID del resultado

Editar campo de un step del resultado › Request Body

EditFieldRequest

editedBy

string · required

Usuario que realiza la edición

Example: admin@example.com

stepKey

string · required

Clave del step donde está el campo

Example: step02

fieldPath

string · required

Ruta del campo a editar (notación de punto)

Example: formData.personalInfo.firstName

newValue

required

Nuevo valor del campo

Example: Andre

changeReason

string

Razón del cambio (para auditoría)

Example: Corrección de error tipográfico

Editar campo de un step del resultado › Responses

Campo actualizado exitosamente

success

boolean

message

string

Agregar comentario al resultado

POST

https://api-id-dev.adamoservices.co/api/v1

/results/{uuid}/comments

Permite agregar un comentario al resultado con historial completo. Los comentarios pueden ser de tipo general, alerta, revisión o aprobación.

Permiso requerido: adamo_id:activity:comment

Agregar comentario al resultado › path Parameters

uuid

string · uuid · required

UUID del resultado

Agregar comentario al resultado › Request Body

AddCommentRequest

createdBy

string · required

Usuario que crea el comentario

Example: revisor@example.com

content

string · required

Contenido del comentario

Example: Esta persona ya es residente, evaluar muy atentamente los datos enviados

commentType

string · enum

Tipo de comentario

Enum values:

general

alert

review

approval

Example: alert

relatedStepKey

string

Step relacionado (opcional)

Example: step02

relatedFieldPath

string

Campo relacionado (opcional)

Example: formData.personalInfo.address

Agregar comentario al resultado › Responses

Comentario agregado exitosamente

success

boolean

message

string

POST/results/{uuid}/comments

curl https://api-id-dev.adamoservices.co/api/v1/results/:uuid/comments \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "createdBy": "revisor@example.com",
  "content": "Esta persona ya es residente, evaluar muy atentamente los datos enviados",
  "commentType": "alert",
  "relatedStepKey": "step02",
  "relatedFieldPath": "formData.personalInfo.address"
}'

Example Request Body

{
  "createdBy": "revisor@example.com",
  "content": "Esta persona ya es residente, evaluar muy atentamente los datos enviados",
  "commentType": "alert",
  "relatedStepKey": "step02",
  "relatedFieldPath": "formData.personalInfo.address"
}

json

Example Responses

{
  "success": true,
  "message": "Comment added successfully"
}

json

application/json

Editar comentario existente

PATCH

https://api-id-dev.adamoservices.co/api/v1

/results/{uuid}/comments/{commentId}

Permite editar el contenido de un comentario existente en un resultado.

Permiso requerido: adamo_id:activity:comment

Editar comentario existente › path Parameters

uuid

string · uuid · required

UUID del resultado

commentId

string · uuid · required

UUID del comentario a editar

Editar comentario existente › Request Body

editedBy

string · required

Usuario que edita el comentario

Example: admin@example.com

content

string · required

Nuevo contenido del comentario

Example: Comentario actualizado con nueva información

Editar comentario existente › Responses

Comentario actualizado exitosamente

success

boolean

message

string

Obtener historial de cambios y comentarios

GET

https://api-id-dev.adamoservices.co/api/v1

/results/{uuid}/history

Retorna el historial completo de cambios realizados y comentarios agregados al resultado, junto con estadísticas.

Permiso requerido: adamo_id:audit_log:full:read

Obtener historial de cambios y comentarios › path Parameters

uuid

string · uuid · required

UUID del resultado

Obtener historial de cambios y comentarios › Responses

Historial obtenido exitosamente

ResultHistoryResponse

success

boolean

object

GET/results/{uuid}/history

curl https://api-id-dev.adamoservices.co/api/v1/results/:uuid/history \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "resultUuid": "00000000-0000-0000-0000-000000000000",
    "changeHistory": [
      {
        "changeId": "00000000-0000-0000-0000-000000000000",
        "changedAt": "2024-08-25T15:00:00Z",
        "changedBy": "changedBy",
        "stepKey": "stepKey",
        "fieldPath": "fieldPath",
        "previousValue": {},
        "newValue": {},
        "changeReason": "changeReason"
      }
    ],
    "comments": [
      {
        "commentId": "00000000-0000-0000-0000-000000000000",
        "createdAt": "2024-08-25T15:00:00Z",
        "createdBy": "createdBy",
        "content": "content",
        "commentType": "general",
        "isEdited": true,
        "editedAt": "2024-08-25T15:00:00Z",
        "editedBy": "editedBy"
      }
    ],
    "statistics": {
      "totalChanges": 3,
      "totalComments": 5
    }
  }
}

json

application/json

Aprobar warnings de un step KYC

POST

https://api-id-dev.adamoservices.co/api/v1

/results/kyc/{uuid}/steps/{stepKey}/warnings/approve

Aprueba todos los warnings de un step específico del resultado KYC. Si todos los warnings de todos los steps quedan resueltos, el overallStatus cambia a completed.

Permiso requerido: adamo_id:risk_alerts:resolve

Aprobar warnings de un step KYC › path Parameters

uuid

string · uuid · required

UUID del resultado KYC

stepKey

string · required

Clave del step (ej: id-document-verification, liveness-check)

Aprobar warnings de un step KYC › Request Body optional

resolutionComment

string

Comentario opcional sobre la resolución

Example: Warnings revisados y aprobados manualmente

Aprobar warnings de un step KYC › Responses

Warnings aprobados exitosamente

success

boolean

message

string

object

POST/results/kyc/{uuid}/steps/{stepKey}/warnings/approve

curl https://api-id-dev.adamoservices.co/api/v1/results/kyc/:uuid/steps/:stepKey/warnings/approve \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "resolutionComment": "Warnings revisados y aprobados manualmente"
}'

Example Request Body

{
  "resolutionComment": "Warnings revisados y aprobados manualmente"
}

json

Example Responses

{
  "success": true,
  "message": "Warnings aprobados exitosamente",
  "data": {
    "stepKey": "id-document-verification",
    "warningsApproved": 2,
    "warningsRejected": 0,
    "allWarningsResolved": true,
    "overallStatus": "completed",
    "reviewedAt": "2024-08-25T15:00:00Z",
    "reviewedBy": "reviewedBy",
    "rejectionReason": "rejectionReason"
  }
}

json

application/json

Rechazar warnings de un step KYC

POST

https://api-id-dev.adamoservices.co/api/v1

/results/kyc/{uuid}/steps/{stepKey}/warnings/reject

Rechaza todos los warnings de un step específico del resultado KYC. El overallStatus del resultado cambia a rejected.

Permiso requerido: adamo_id:risk_alerts:resolve

Rechazar warnings de un step KYC › path Parameters

uuid

string · uuid · required

UUID del resultado KYC

stepKey

string · required

Clave del step (ej: id-document-verification, liveness-check)

Rechazar warnings de un step KYC › Request Body

rejectionReason

string · minLength: 3 · maxLength: 500 · required

Razón principal del rechazo

Example: Documento no reconocido

rejectionComment

string · maxLength: 2000

Comentarios adicionales sobre el rechazo

Example: Formato obsoleto o no válido para el país

Rechazar warnings de un step KYC › Responses

Warnings rechazados exitosamente

success

boolean

message

string

object

POST/results/kyc/{uuid}/steps/{stepKey}/warnings/reject

curl https://api-id-dev.adamoservices.co/api/v1/results/kyc/:uuid/steps/:stepKey/warnings/reject \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "rejectionReason": "Documento no reconocido",
  "rejectionComment": "Formato obsoleto o no válido para el país"
}'

Example Request Body

{
  "rejectionReason": "Documento no reconocido",
  "rejectionComment": "Formato obsoleto o no válido para el país"
}

json

Example Responses

{
  "success": true,
  "message": "Warnings aprobados exitosamente",
  "data": {
    "stepKey": "id-document-verification",
    "warningsApproved": 2,
    "warningsRejected": 0,
    "allWarningsResolved": true,
    "overallStatus": "completed",
    "reviewedAt": "2024-08-25T15:00:00Z",
    "reviewedBy": "reviewedBy",
    "rejectionReason": "rejectionReason"
  }
}

json

application/json

Eliminar archivo de un resultado

DELETE

https://api-id-dev.adamoservices.co/api/v1

/results/{uuid}/files/{fileId}

Elimina un archivo del FlowRunResult y de S3. Requiere token de usuario autenticado.

Permiso requerido: adamo_id:evidence:read

Eliminar archivo de un resultado › path Parameters

uuid

string · uuid · required

UUID del FlowRunResult

fileId

string · required

ID del archivo a eliminar

Eliminar archivo de un resultado › Responses

Archivo eliminado exitosamente

success

boolean

message

string

Ejecución de flujos