Imagy Platform

Appearance

ImagID — API Reference ​

Endpoints Publicos (via Gateway) ​

Todos requieren autenticacion JWT. Operan dentro del contexto del tenant del token.

Perfiles ​

MetodoEndpointRol requeridoDescripcion
GET/api/v1/subjectsoperator, tenant_adminListar sujetos del tenant (paginado)
GET/api/v1/subjects/{id}operator, tenant_adminObtener perfil completo del sujeto
GET/api/v1/subjects/lookupoperator, tenant_adminBuscar sujeto por documento

Historial ​

MetodoEndpointRol requeridoDescripcion
GET/api/v1/subjects/{id}/eventsoperator, tenant_adminTimeline de eventos del sujeto
GET/api/v1/subjects/{id}/events/summaryoperator, tenant_adminResumen de actividad

Dispositivos ​

MetodoEndpointRol requeridoDescripcion
GET/api/v1/subjects/{id}/devicesoperator, tenant_adminListar dispositivos conocidos
GET/api/v1/subjects/{id}/devices/{deviceId}operator, tenant_adminDetalle de un dispositivo

Listas de Control ​

MetodoEndpointRol requeridoDescripcion
GET/api/v1/subjects/{id}/listsoperator, tenant_adminListar entradas activas en listas
POST/api/v1/subjects/{id}/liststenant_adminAgregar sujeto a una lista
DELETE/api/v1/subjects/{id}/lists/{entryId}tenant_adminRemover de una lista
GET/api/v1/liststenant_adminListar todas las entradas por tipo

Alertas ​

MetodoEndpointRol requeridoDescripcion
GET/api/v1/subjects/{id}/alertsoperator, tenant_adminListar alertas del sujeto
GET/api/v1/alertsoperator, tenant_adminListar todas las alertas del tenant
PATCH/api/v1/alerts/{id}tenant_adminActualizar estado de alerta

Trust Score ​

MetodoEndpointRol requeridoDescripcion
GET/api/v1/subjects/{id}/trust-scoreoperator, tenant_adminObtener trust score actual
GET/api/v1/subjects/{id}/trust-score/historytenant_adminHistorial de cambios del score

Endpoints Internos (servicio-a-servicio) ​

Invocados por otros dominios con JWT propagado. No expuestos en el API Gateway publico.

MetodoEndpointConsumidorDescripcion
GET/internal/v1/subjects/{id}/metricsImagFlowMetricas agregadas para reglas
GET/internal/v1/subjects/{id}/trust-scoreImagFlow, ImagLendTrust score actual
GET/internal/v1/subjects/{id}/lists/checkImagFlow, ImagLendVerificar pertenencia a listas
GET/internal/v1/subjects/{id}/devicesImagLendDispositivos conocidos
GET/internal/v1/subjects/lookupImagFlow, ImagLendBuscar por documento

Ejemplos de Request/Response ​

Buscar Sujeto por Documento ​

http
GET /api/v1/subjects/lookup?identifier_type=cedula&identifier_value=1234567890
Authorization: Bearer {jwt}

Response 200:

json
{
  "data": {
    "subject_id": "subject-uuid",
    "identifier_type": "cedula",
    "identifier_value": "1234567890",
    "full_name": "Juan Perez",
    "tenant_view": {
      "status": "active",
      "trust_score": 72.50,
      "total_interactions": 15,
      "total_approvals": 12,
      "total_rejections": 3,
      "total_defaults": 0,
      "first_interaction_at": "2025-03-15T08:00:00Z",
      "last_interaction_at": "2026-05-18T10:30:00Z"
    }
  },
  "metadata": {
    "request_id": "req-abc123",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Obtener Timeline de Eventos ​

http
GET /api/v1/subjects/subject-uuid/events?page=1&page_size=20&sort=desc
Authorization: Bearer {jwt}

Response 200:

json
{
  "data": [
    {
      "id": "event-uuid-1",
      "event_type": "flow.execution.completed",
      "event_source": "imagy-flow-engine",
      "event_data": {
        "flow_name": "Validacion de Identidad",
        "result": "approved",
        "confidence": 0.95
      },
      "device_info": {
        "fingerprint": "fp-abc123",
        "ip": "190.25.100.50",
        "geo_city": "Bogota"
      },
      "event_timestamp": "2026-05-18T10:30:00Z"
    },
    {
      "id": "event-uuid-2",
      "event_type": "lending.credit.disbursed",
      "event_source": "imagy-lending",
      "event_data": {
        "credit_id": "credit-uuid",
        "amount": 5000000,
        "currency": "COP"
      },
      "device_info": null,
      "event_timestamp": "2026-05-17T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 45,
    "total_pages": 3
  },
  "metadata": {
    "request_id": "req-def456",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Agregar a Lista ​

http
POST /api/v1/subjects/subject-uuid/lists
Content-Type: application/json
Authorization: Bearer {jwt}
json
{
  "list_type": "blacklist",
  "reason": "Multiples intentos de fraude detectados",
  "expires_in_days": null,
  "metadata": {
    "related_alert_id": "alert-uuid",
    "evidence": "3 rechazos consecutivos por biometria no coincidente"
  }
}

Response 201:

json
{
  "data": {
    "id": "entry-uuid",
    "subject_id": "subject-uuid",
    "list_type": "blacklist",
    "reason": "Multiples intentos de fraude detectados",
    "added_at": "2026-05-18T10:30:00Z",
    "expires_at": null,
    "added_by_type": "user"
  },
  "metadata": {
    "request_id": "req-ghi789",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Verificar Listas (interno) ​

http
GET /internal/v1/subjects/subject-uuid/lists/check?list_types=blacklist,watchlist
Authorization: Bearer {jwt-propagado}

Response 200:

json
{
  "data": {
    "subject_id": "subject-uuid",
    "checks": {
      "blacklist": {
        "is_listed": true,
        "reason": "Multiples intentos de fraude detectados",
        "added_at": "2026-05-18T10:30:00Z",
        "expires_at": null
      },
      "watchlist": {
        "is_listed": false
      }
    }
  }
}

Obtener Metricas (interno, para ImagFlow Rules Engine) ​

http
GET /internal/v1/subjects/subject-uuid/metrics
Authorization: Bearer {jwt-propagado}

Response 200:

json
{
  "data": {
    "subject_id": "subject-uuid",
    "trust_score": 72.50,
    "total_interactions": 15,
    "total_approvals": 12,
    "total_rejections": 3,
    "total_defaults": 0,
    "approval_rate": 0.80,
    "days_since_first_interaction": 430,
    "days_since_last_interaction": 0,
    "devices_count": 3,
    "recent_rejections_30d": 1,
    "lists": {
      "blacklisted": false,
      "whitelisted": false,
      "watchlisted": true
    }
  }
}

Obtener Trust Score (interno) ​

http
GET /internal/v1/subjects/subject-uuid/trust-score
Authorization: Bearer {jwt-propagado}

Response 200:

json
{
  "data": {
    "subject_id": "subject-uuid",
    "trust_score": 72.50,
    "classification": "normal",
    "last_calculated_at": "2026-05-18T10:30:00Z",
    "factors": {
      "approvals_contribution": 60.0,
      "rejections_contribution": -30.0,
      "defaults_contribution": 0.0,
      "tenure_contribution": 14.0,
      "device_contribution": -2.0,
      "base_score": 50.0
    }
  }
}

Listar Dispositivos ​

http
GET /api/v1/subjects/subject-uuid/devices
Authorization: Bearer {jwt}

Response 200:

json
{
  "data": [
    {
      "id": "device-uuid-1",
      "device_fingerprint": "fp-abc123",
      "ip_address": "190.25.100.50",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "geo_country": "Colombia",
      "geo_city": "Bogota",
      "access_count": 8,
      "first_seen_at": "2025-06-10T09:00:00Z",
      "last_seen_at": "2026-05-18T10:30:00Z"
    },
    {
      "id": "device-uuid-2",
      "device_fingerprint": "fp-def456",
      "ip_address": "181.50.200.10",
      "user_agent": "Mozilla/5.0 (Linux; Android 14)",
      "geo_country": "Colombia",
      "geo_city": "Medellin",
      "access_count": 3,
      "first_seen_at": "2026-04-01T11:00:00Z",
      "last_seen_at": "2026-05-10T15:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 2,
    "total_pages": 1
  },
  "metadata": {
    "request_id": "req-jkl012",
    "timestamp": "2026-05-18T10:30:00Z"
  }
}

Filtros y Paginacion ​

Parametros de Paginacion ​

Todos los endpoints de listado soportan:

ParametroTipoDefaultDescripcion
pageINT1Numero de pagina
page_sizeINT20Items por pagina (max 100)
sortSTRINGdescOrden: asc o desc
sort_bySTRINGvariaCampo de ordenamiento

Filtros por Endpoint ​

GET /api/v1/subjects

FiltroTipoDescripcion
statusSTRINGFiltrar por estado: active, flagged, blacklisted
trust_score_minDECIMALScore minimo
trust_score_maxDECIMALScore maximo
last_interaction_afterISO8601Interaccion despues de fecha

GET /api/v1/subjects/{id}/events

FiltroTipoDescripcion
event_typeSTRINGFiltrar por tipo de evento
event_sourceSTRINGFiltrar por dominio origen
fromISO8601Eventos desde fecha
toISO8601Eventos hasta fecha

GET /api/v1/alerts

FiltroTipoDescripcion
statusSTRINGopen, acknowledged, resolved, dismissed
severitySTRINGlow, medium, high, critical
alert_typeSTRINGTipo de alerta

Headers Especiales ​

HeaderDireccionDescripcion
X-Request-IdResponseID de trazabilidad
X-Cache-HitResponsetrue si la respuesta vino de cache
Cache-ControlResponseDirectivas de cache para trust score y listas

Codigos de Estado ​

StatusCuando
200Operacion exitosa
201Entrada en lista creada
400Parametros invalidos
401No autenticado
403Sin permisos para la operacion
404Sujeto no encontrado en este tenant
409Sujeto ya esta en la lista indicada
429Rate limit excedido
500Error interno

Reimagine Tech LLC — Documentacion Interna

2026 Reimagine Tech LLC