Flujos

Gestión de flujos de verificación KYC y KYB

Crear un flujo de verificación

POST

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

/flow

Crea una nueva definición de flujo KYC o KYB con sus pasos, configuración de tiempo límite y política de reintentos.

Permiso requerido: adamo_id:verifications:prepare_start

El flujo se crea y publica automáticamente en estado published. No es necesario un paso adicional de publicación; una vez creado, se pueden enviar invitaciones de inmediato.

Crear un flujo de verificación › Request Body

CreateFlowRequest

type

string · enum · required

Tipo de flujo de verificación.

Enum values:

kyc

kyb

kyb_company

Example: kyc

name

string · minLength: 1 · maxLength: 100 · required

Nombre descriptivo del flujo.

Example: KYC Básico

FlowStepInput[] · minItems: 1 · maxItems: 20 · required

Lista de pasos del flujo. Los order deben ser consecutivos empezando en 1 y las key deben ser únicas.

object · required

Tiempo máximo que tiene el usuario para completar el flujo desde que recibe el link.

organizationId

string · uuid

UUID de la organización. Si se omite, se usa la del token.

Example: 550e8400-e29b-41d4-a716-446655440000

code

string · minLength: 3 · maxLength: 50 · pattern: ^[A-Z0-9_]+$

Código único del flujo dentro de la organización. Solo letras mayúsculas, números y guiones bajos.

Example: KYC_EMPLEADOS_2024

description

string · maxLength: 500

Descripción opcional del propósito del flujo.

Example: Flujo de verificación para incorporación de empleados

tags

string[]

Etiquetas para organizar y filtrar flujos.

Example: ["onboarding","empleados"]

Crear un flujo de verificación › Responses

Flujo creado exitosamente

success

boolean

FlowDefinition

POST/flow

curl https://api-id-dev.adamoservices.co/api/v1/flow \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "KYC Básico",
  "type": "kyc",
  "code": "KYC_BASICO",
  "description": "Flujo de verificación para personas naturales",
  "timeLimit": {
    "value": 72,
    "unit": "hours"
  },
  "steps": [
    {
      "key": "id-document",
      "label": "Verificación de documento",
      "type": "id_document",
      "order": 1,
      "required": true,
      "provider": {
        "mode": "internal",
        "serviceCode": "adamo-id-ocr-ms",
        "config": {
          "acceptedDocuments": [
            "passport",
            "national_id"
          ],
          "minimumConfidenceLevel": 85,
          "verifyExpiration": true
        }
      }
    },
    {
      "key": "liveness-check",
      "label": "Verificación de vida",
      "type": "liveness",
      "order": 2,
      "required": true,
      "provider": {
        "mode": "internal",
        "serviceCode": "adamo-id-liveness-ms",
        "config": {
          "minimumConfidenceLevel": 90,
          "maxAttempts": 3
        }
      }
    }
  ]
}'

Example Request Body

{
  "name": "KYC Básico",
  "type": "kyc",
  "code": "KYC_BASICO",
  "description": "Flujo de verificación para personas naturales",
  "timeLimit": {
    "value": 72,
    "unit": "hours"
  },
  "steps": [
    {
      "key": "id-document",
      "label": "Verificación de documento",
      "type": "id_document",
      "order": 1,
      "required": true,
      "provider": {
        "mode": "internal",
        "serviceCode": "adamo-id-ocr-ms",
        "config": {
          "acceptedDocuments": [
            "passport",
            "national_id"
          ],
          "minimumConfidenceLevel": 85,
          "verifyExpiration": true
        }
      }
    },
    {
      "key": "liveness-check",
      "label": "Verificación de vida",
      "type": "liveness",
      "order": 2,
      "required": true,
      "provider": {
        "mode": "internal",
        "serviceCode": "adamo-id-liveness-ms",
        "config": {
          "minimumConfidenceLevel": 90,
          "maxAttempts": 3
        }
      }
    }
  ]
}

json

application/json

Example Responses

No example specified for this content type

application/json

Obtener un flujo de verificación

GET

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

/flow/{id}

Obtiene los detalles completos de un flujo por su ID, incluyendo pasos, configuración y estadísticas.

Permiso requerido: adamo_id:verifications:prepare_start

Obtener un flujo de verificación › path Parameters

id

string · uuid · required

UUID del flujo

Obtener un flujo de verificación › Responses

Flujo obtenido exitosamente

success

boolean

FlowDefinition

Enviar invitación de verificación

POST

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

/flow/{id}/invitations

Envía una invitación para que un destinatario complete el flujo de verificación asociado.

Permiso requerido: adamo_id:verifications:prepare_start

El flujo debe estar en estado published (condición que se cumple automáticamente al crear el flujo).

Reglas de validación:

Se requiere al menos recipient.email o recipient.phone.
Si channels incluye email, el campo recipient.email es obligatorio.
Si channels incluye sms, whatsapp o telegram, el campo recipient.phone es obligatorio.
link_only genera el enlace público sin enviar notificación por ningún canal.

URLs públicas generadas:

Flujos KYC: https://verification-v2.adamoservices.co/verify/{token}
Flujos KYB: https://dev-journey-id.adamoservices.co/verify?token={token}

Enviar invitación de verificación › path Parameters

id

string · uuid · required

UUID del flujo al cual se asocia la invitación

Enviar invitación de verificación › Request Body

SendInvitationRequest

InvitationListItem/properties/recipient · required

Datos del destinatario. Se requiere al menos email o phone.

channels

DeliveryChannel[] · minItems: 1 · required

Canales por los cuales se enviará la invitación. Se permite más de uno simultáneamente.

Si incluye email → recipient.email es obligatorio.
Si incluye sms, whatsapp o telegram → recipient.phone es obligatorio.
link_only genera el enlace sin enviar notificación.

Enum values:

sms

link_only

Example: ["email","whatsapp"]

expirationHours

integer · min: 1 · max: 168

Horas hasta que expire la invitación (máximo 7 días).

Example: 48

Default: 72

object

Metadatos adicionales asociados a la invitación (referencia interna, campaña, etc.).

Example: {"campaignId":"camp_2024_q1","internalRef":"SOL-2024-00456"}

Enviar invitación de verificación › Responses

Invitación enviada exitosamente

InvitationResponse

success

boolean

object

message

string

Enviar invitaciones masivas

POST

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

/flow/{id}/invitations/bulk

Envía múltiples invitaciones a partir de un archivo Excel (.xlsx) con la lista de destinatarios.

Permiso requerido: adamo_id:verifications:prepare_start

El archivo debe contener las columnas: name (opcional), email, phone (opcional), channels (separados por coma).

El flujo debe estar en estado published.

Enviar invitaciones masivas › path Parameters

id

string · uuid · required

UUID del flujo al cual se asocian las invitaciones

Enviar invitaciones masivas › Request Body

file

string · required

Archivo Excel (.xlsx) con columnas: name, email, phone, channels

Enviar invitaciones masivas › Responses

Invitaciones procesadas

BulkInvitationResponse

success

boolean

object

POST/flow/{id}/invitations/bulk

curl https://api-id-dev.adamoservices.co/api/v1/flow/:id/invitations/bulk \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer <token>' \
  --form 'file=file'

Example Request Body

{
  "file": "file"
}

text

Example Responses

{
  "success": true,
  "data": {
    "total": 50,
    "successful": 47,
    "failed": 3,
    "errors": [
      {
        "row": 12,
        "email": "correo-invalido@",
        "reason": "Email format is invalid"
      },
      {
        "row": 28,
        "email": "sin-telefono@test.com",
        "reason": "recipient.phone is required when channels include 'whatsapp'"
      },
      {
        "row": 45,
        "email": "",
        "reason": "At least email or phone is required"
      }
    ]
  }
}

json

application/json

Listar invitaciones enviadas

GET

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

/flow/invitations

Obtiene la lista de invitaciones enviadas por la organización con paginación y filtros opcionales.

Permiso requerido: adamo_id:verifications:prepare_start

Listar invitaciones enviadas › query Parameters

page

integer · min: 1

Número de página

Default: 1

limit

integer · min: 1 · max: 100

Cantidad de resultados por página

Default: 20

status

string · enum

Filtrar por estado de la invitación

Enum values:

created

sent

used

failed

expired

flowId

string · uuid

Filtrar por ID de flujo

Listar invitaciones enviadas › Responses

Lista de invitaciones obtenida exitosamente

success

boolean

InvitationListItem[]

object

GET/flow/invitations

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

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "00000000-0000-0000-0000-000000000000",
      "type": "kyc",
      "flowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "recipient": {
        "name": "Juan Pérez",
        "email": "juan.perez@empresa.com",
        "phone": "+57 300 1234567"
      },
      "channels": [
        "email"
      ],
      "status": "sent",
      "linkToken": "eyJhbGciOiJIUzI1NiJ9...",
      "sentAt": "2026-06-04T10:00:00Z",
      "usedAt": "2024-08-25T15:00:00Z",
      "expiresAt": "2026-06-07T10:00:00Z",
      "createdAt": "2026-06-04T10:00:00Z",
      "updatedAt": "2026-06-04T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

json

application/json

Ejecución de flujos

Crear un flujo de verificación

POST

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

/flow

Crea una nueva definición de flujo KYC o KYB con sus pasos, configuración de tiempo límite y política de reintentos.

Permiso requerido: adamo_id:verifications:prepare_start

El flujo se crea y publica automáticamente en estado published. No es necesario un paso adicional de publicación; una vez creado, se pueden enviar invitaciones de inmediato.

Crear un flujo de verificación › Request Body

CreateFlowRequest

type

string · enum · required

Tipo de flujo de verificación.

Enum values:

kyc

kyb

kyb_company

Example: kyc

name

string · minLength: 1 · maxLength: 100 · required

Nombre descriptivo del flujo.

Example: KYC Básico

FlowStepInput[] · minItems: 1 · maxItems: 20 · required

Lista de pasos del flujo. Los order deben ser consecutivos empezando en 1 y las key deben ser únicas.

object · required

Tiempo máximo que tiene el usuario para completar el flujo desde que recibe el link.

organizationId

string · uuid

UUID de la organización. Si se omite, se usa la del token.

Example: 550e8400-e29b-41d4-a716-446655440000

code

string · minLength: 3 · maxLength: 50 · pattern: ^[A-Z0-9_]+$

Código único del flujo dentro de la organización. Solo letras mayúsculas, números y guiones bajos.

Example: KYC_EMPLEADOS_2024

description

string · maxLength: 500

Descripción opcional del propósito del flujo.

Example: Flujo de verificación para incorporación de empleados

tags

string[]

Etiquetas para organizar y filtrar flujos.

Example: ["onboarding","empleados"]

Crear un flujo de verificación › Responses

Flujo creado exitosamente

success

boolean

FlowDefinition

Obtener un flujo de verificación

GET

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

/flow/{id}

Obtiene los detalles completos de un flujo por su ID, incluyendo pasos, configuración y estadísticas.

Permiso requerido: adamo_id:verifications:prepare_start

Obtener un flujo de verificación › path Parameters

id

string · uuid · required

UUID del flujo

Obtener un flujo de verificación › Responses

Flujo obtenido exitosamente

success

boolean

FlowDefinition

Enviar invitación de verificación

POST

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

/flow/{id}/invitations

Envía una invitación para que un destinatario complete el flujo de verificación asociado.

Permiso requerido: adamo_id:verifications:prepare_start

El flujo debe estar en estado published (condición que se cumple automáticamente al crear el flujo).

Reglas de validación:

Se requiere al menos recipient.email o recipient.phone.
Si channels incluye email, el campo recipient.email es obligatorio.
Si channels incluye sms, whatsapp o telegram, el campo recipient.phone es obligatorio.
link_only genera el enlace público sin enviar notificación por ningún canal.

URLs públicas generadas:

Flujos KYC: https://verification-v2.adamoservices.co/verify/{token}
Flujos KYB: https://dev-journey-id.adamoservices.co/verify?token={token}

Enviar invitación de verificación › path Parameters

id

string · uuid · required

UUID del flujo al cual se asocia la invitación

Enviar invitación de verificación › Request Body

SendInvitationRequest

InvitationListItem/properties/recipient · required

Datos del destinatario. Se requiere al menos email o phone.

channels

DeliveryChannel[] · minItems: 1 · required

Canales por los cuales se enviará la invitación. Se permite más de uno simultáneamente.

Si incluye email → recipient.email es obligatorio.
Si incluye sms, whatsapp o telegram → recipient.phone es obligatorio.
link_only genera el enlace sin enviar notificación.

Enum values:

sms

link_only

Example: ["email","whatsapp"]

expirationHours

integer · min: 1 · max: 168

Horas hasta que expire la invitación (máximo 7 días).

Example: 48

Default: 72

object

Metadatos adicionales asociados a la invitación (referencia interna, campaña, etc.).

Example: {"campaignId":"camp_2024_q1","internalRef":"SOL-2024-00456"}

Enviar invitación de verificación › Responses

Invitación enviada exitosamente

InvitationResponse

success

boolean

object

message

string

Enviar invitaciones masivas

POST

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

/flow/{id}/invitations/bulk

Envía múltiples invitaciones a partir de un archivo Excel (.xlsx) con la lista de destinatarios.

Permiso requerido: adamo_id:verifications:prepare_start

El archivo debe contener las columnas: name (opcional), email, phone (opcional), channels (separados por coma).

El flujo debe estar en estado published.

Enviar invitaciones masivas › path Parameters

id

string · uuid · required

UUID del flujo al cual se asocian las invitaciones

Enviar invitaciones masivas › Request Body

file

string · required

Archivo Excel (.xlsx) con columnas: name, email, phone, channels

Enviar invitaciones masivas › Responses

Invitaciones procesadas

BulkInvitationResponse

success

boolean

object

Listar invitaciones enviadas

GET

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

/flow/invitations

Obtiene la lista de invitaciones enviadas por la organización con paginación y filtros opcionales.

Permiso requerido: adamo_id:verifications:prepare_start

Listar invitaciones enviadas › query Parameters

page

integer · min: 1

Número de página

Default: 1

limit

integer · min: 1 · max: 100

Cantidad de resultados por página

Default: 20

status

string · enum

Filtrar por estado de la invitación

Enum values:

created

sent

used

failed

expired

flowId

string · uuid

Filtrar por ID de flujo

Listar invitaciones enviadas › Responses

Lista de invitaciones obtenida exitosamente

success

boolean

InvitationListItem[]

object