> ## 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 de riesgo de email: entregabilidad y filtraciones

> Didit evalúa el riesgo de un email sin enviar OTP: entregabilidad, dominios desechables, filtraciones y fraude en una llamada servidor a servidor.

Usa `POST /v3/email/risk/` cuando necesites inteligencia sobre correos electrónicos sin pedir al usuario que introduzca un código de un solo uso.

No envía ningún correo electrónico. Crea una sesión de API, enriquece la dirección, aplica tus reglas de riesgo de correo electrónico y devuelve, en una única respuesta síncrona, el mismo bloque normalizado de correo electrónico que usa la Verificación de correo electrónico.

Cuando se guarda la solicitud, Didit también puede usar la dirección de correo electrónico evaluada como evidencia agregada en **Networks**. Los grafos de red pueden mostrar inteligencia de correo electrónico de alto riesgo, contexto de filtraciones y cobertura de perfiles sociales en señales de correo electrónico compartidas, pero no revelan la dirección de correo electrónico sin procesar a otras organizaciones.

## Cómo interpretar la respuesta

* `status` es la decisión final de esta sesión de API. Normalmente es `Approved`; la evaluación de riesgo puede dar como resultado `In Review` o `Declined`.
* `email.is_breached`, `email.is_disposable` y `email.is_undeliverable` son las señales estables de sí/no para la lógica de tu aplicación.
* `email.breaches` enumera las filtraciones conocidas más recientes que contienen la dirección, cuando hay cobertura disponible, con la fecha de la filtración y las clases de datos expuestas.
* `email.email_intelligence.score` usa una escala de riesgo de 0 a 100 en la que un número más alto indica un riesgo mayor. `breach_risk_level` (`Low`, `Medium`, `High`) y `no_of_breaches` son vistas derivadas.
* `email.email_intelligence.reason_codes` explica qué señales normalizadas contribuyeron al resultado. La lista de valores puede crecer con el tiempo, así que no rechaces los códigos desconocidos.
* `email.email_intelligence` y `email.enrichment` son alias de compatibilidad que contienen el mismo objeto normalizado. Las integraciones nuevas pueden leer `email.enrichment`.
* `email.matches` enumera otras sesiones de tu aplicación en las que un usuario distinto usó la misma dirección. Úsalo para detectar cuentas duplicadas.
* `request_id` es el ID de la sesión de API. Guárdalo junto con `vendor_data` si necesitas correlacionar el resultado con webhooks posteriores o con la actividad en la consola.

> [!WARNING]
>
> `email.email_intelligence` y `email.enrichment` se proporcionan según disponibilidad. Una consulta completada puede omitir ambos cuando no se devuelven datos de inteligencia utilizables para esa dirección, ese dominio o ese plan. Basa tus reglas primero en `is_breached`, `is_disposable` y `is_undeliverable`, y trata la ausencia de inteligencia como "desconocido", no como "seguro".

## Complemento de huella social

Establece `enable_social` en `true` para añadir un bloque `email_social` a la respuesta, dentro de `email`: las plataformas en línea en las que está registrada esta dirección de correo electrónico, agrupadas por categoría, con los recuentos resumidos y los detalles de perfil que devuelvan nuestros socios de datos.

* `email.email_social.profiles_registered` y `email.email_social.profiles_checked` son las cifras principales: las plataformas en las que se ha confirmado que la dirección de correo electrónico está registrada, del total de plataformas evaluadas.
* `email.email_social.registered_platforms` y `email.email_social.not_registered_platforms` enumeran cada plataforma con su `category` y su `scope` (`global`, o `local` para plataformas específicas de una región).
* `email.email_social.categories` indica el recuento de registros y la proporción por categoría, y `email.email_social.profiles` incluye los detalles de perfil por plataforma cuando una plataforma los expone (nombre, URL de la foto, texto de presentación, estado de privacidad e indicador de cuenta de empresa).
* Los índices resumidos (`digital_footprint_diversity`, `digital_sophistication_index`, `engagement_depth_index`, `subscription_affordability_index`) son indicadores compuestos de 0 a 10. Cualquier recuento puede ser `null` cuando la comprobación no devolvió datos para él.

`profiles_registered: 0` es una respuesta real, no un fallo: se comprobaron las plataformas y la dirección de correo electrónico no se encontró en ninguna de ellas, lo que es una señal habitual de identidad sintética. Este endpoint no actúa sobre ella por sí solo: usa `email_no_social_presence_action` en un flujo para convertirla en un veredicto de revisión o de rechazo.

El bloque no aparece cuando `enable_social` no está establecido, ni tampoco cuando no se pudo completar la comprobación social, en cuyo caso no se factura.

## Comportamiento en sandbox

Las claves de sandbox validan la solicitud y devuelven datos aprobados deterministas. No envían ningún correo electrónico, no consumen créditos, no crean una sesión ni contribuyen a **Networks**. Con `enable_social` configurado, también devuelven un bloque `email_social` determinista.

## Facturación

Las llamadas a la Email Risk API cuestan \$0.04 a precio de lista, menos de lo que costaría una Verificación de correo electrónico completa, porque no se envía ningún correo electrónico. Una solicitud en producción se factura en cuanto comienza la consulta, aunque algunos campos de disponibilidad no garantizada no estén disponibles.

El complemento de huella social se factura por separado: una unidad de `email_social` por solicitud, además del precio de la Email Risk API, siempre que la comprobación se complete. La comprobación de créditos previa a la consulta se aplica a ambos.


## OpenAPI

````yaml es/openapi-25.json POST /v3/email/risk/
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/email/risk/:
    post:
      tags:
        - Standalone APIs
      summary: Calcular la puntuación de riesgo de una dirección de correo electrónico
      description: >-
        Devuelve señales de entregabilidad, de direcciones desechables, de
        filtraciones, de coincidencia entre sesiones y de inteligencia de riesgo
        normalizada sin enviar un OTP. El endpoint crea una sesión de API y
        devuelve su id como `request_id`.


        **Decisión.** El `status` de nivel superior refleja `email.status`.
        Normalmente es `Approved`; la evaluación de riesgo puede producir `In
        Review` o `Declined`.


        **Alias de compatibilidad.** Las respuestas en producción exponen el
        objeto de inteligencia normalizado como `email.email_intelligence` y
        también como `email.enrichment`. Los valores son idénticos. Las nuevas
        integraciones pueden leer `email.enrichment`. Ambas claves están
        ausentes cuando no se devolvieron datos de inteligencia utilizables.


        **Facturación.** Las llamadas en producción usan los precios de la Email
        Risk API. La solicitud es facturable en cuanto comienza la consulta,
        aunque algunos campos que se obtienen en la medida de lo posible no
        estén disponibles.


        **Sandbox.** Las claves de sandbox validan la solicitud y devuelven
        datos aprobados deterministas sin enviar ningún correo electrónico,
        consumir créditos, crear una sesión ni contribuir a Networks.


        **Autenticación.** Envía la clave de API de tu aplicación en
        `x-api-key`. Si las credenciales faltan o no son válidas, se devuelve
        `403`: esta API nunca devuelve `401`.


        **Límite de solicitudes.** Cupo de escritura compartido de 300
        solicitudes por minuto por clave de API entre todos los endpoints
        POST/PATCH/DELETE.


        **Huella social.** Establece `enable_social` en `true` para añadir un
        bloque `email_social`: las plataformas en línea en las que está
        registrada esta dirección, con recuentos por categoría y los detalles de
        perfil disponibles. `profiles_registered: 0` significa que se
        comprobaron las plataformas y que la dirección no se encontró en ninguna
        de ellas, lo cual es una respuesta válida y facturable. El bloque está
        ausente cuando no se solicitó el complemento o no se pudo completar la
        comprobación, y en ese caso no se factura. La facturación añade una
        unidad de `email_social` por solicitud, además del precio propio de este
        endpoint.
      operationId: post_v3email_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRiskRequest'
            examples:
              Minimal:
                summary: Puntuar una dirección con los valores predeterminados
                value:
                  email: alice@example.com
              Full context:
                summary: >-
                  Puntuar con señales, indicación de país e identificadores de
                  correlación
                value:
                  email: alice@example.com
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: web
                    os_version: '14.4'
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4
                      Safari/605.1.15
                  vendor_data: lead-123
                  metadata:
                    source: signup_prescreen
      responses:
        '200':
          description: >-
            La evaluación de riesgo se completó. Consulta `status` para ver la
            decisión; el código HTTP siempre es `200` en las consultas
            completadas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRiskResponse'
              examples:
                Clean address:
                  summary: Dirección entregable sin exposición a filtraciones
                  value:
                    request_id: 82397be9-5921-4970-a979-2d5b43e08b33
                    status: Approved
                    email:
                      status: Approved
                      email: alice@example.com
                      is_breached: false
                      breaches: []
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      email_intelligence:
                        score: 4
                        deliverable: high
                        breach_risk_level: Low
                        breach_risk_index: 4
                        is_recent_breach: false
                        is_frequent_breached: false
                        is_disposable: false
                        is_free_domain: false
                        is_breached: false
                        no_of_breaches: 0
                        reason_codes: []
                      enrichment:
                        score: 4
                        deliverable: high
                        breach_risk_level: Low
                        breach_risk_index: 4
                        is_recent_breach: false
                        is_frequent_breached: false
                        is_disposable: false
                        is_free_domain: false
                        is_breached: false
                        no_of_breaches: 0
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Breached address:
                  summary: Dirección encontrada en filtraciones conocidas
                  value:
                    request_id: d1e5c2a8-6f30-4c1a-8b2d-3e4f5a6b7c8d
                    status: In Review
                    email:
                      status: In Review
                      email: bob@example.org
                      is_breached: true
                      breaches:
                        - name: ExampleBreach2023
                          domain: example.org
                          breach_date: '2023-06-01'
                          breach_emails_count: 1200000
                          description: A data breach affecting example.org accounts.
                          logo_path: https://logos.example.org/example.png
                          data_classes:
                            - email_addresses
                            - passwords
                          is_verified: true
                      is_disposable: false
                      is_undeliverable: false
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      email_intelligence:
                        score: 58
                        deliverable: high
                        breach_risk_level: High
                        breach_risk_index: 72
                        is_recent_breach: true
                        is_frequent_breached: true
                        is_disposable: false
                        is_free_domain: true
                        is_breached: true
                        no_of_breaches: 4
                        reason_codes:
                          - code: IR-F784B630
                            direction: risk
                            message: Email's digital footprint diversity is Very Low
                            impact_level: low
                      enrichment:
                        score: 58
                        deliverable: high
                        breach_risk_level: High
                        breach_risk_index: 72
                        is_recent_breach: true
                        is_frequent_breached: true
                        is_disposable: false
                        is_free_domain: true
                        is_breached: true
                        no_of_breaches: 4
                        reason_codes:
                          - code: IR-F784B630
                            direction: risk
                            message: Email's digital footprint diversity is Very Low
                            impact_level: low
                    vendor_data: lead-125
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/EmailRiskValidationError'
        '403':
          $ref: '#/components/responses/RiskPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/email/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "email": "alice@example.com",
                "country_code": "US",
                "vendor_data": "lead-123",
                "metadata": {"source": "signup_prescreen"}
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.email.assess_risk(
                email="alice@example.com",
            )
            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.email.assessRisk({
              email: "alice@example.com",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{\n\tEmail: \"alice@example.com\",\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.EmailRiskRequest;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.email().assessRisk(EmailRiskRequest.builder()
                    .email("alice@example.com")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->email->assessRisk([
                'email' => 'alice@example.com',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.email.assess_risk(email: "alice@example.com")
            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.Email.AssessRiskAsync(new EmailRiskRequest
            {
                Email = "alice@example.com",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    EmailRiskRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Dirección de correo electrónico que se va a puntuar.
          example: alice@example.com
        country_code:
          type: string
          maxLength: 3
          description: >-
            Indicación de país ISO 3166-1 alfa-2 o alfa-3 opcional para la
            cobertura de inteligencia.
          example: US
        signals:
          $ref: '#/components/schemas/RiskSignals'
        vendor_data:
          type: string
          description: >-
            Tu referencia estable para esta solicitud. Se guarda en la sesión de
            API y se devuelve en la respuesta.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Tus metadatos JSON no sensibles. Se almacenan en la sesión de API y
            se devuelven en la respuesta.
        enable_social:
          type: boolean
          default: false
          description: >-
            Si es true, también se consulta la huella social de la dirección:
            las plataformas de correo electrónico, redes sociales,
            profesionales, comercio electrónico y entretenimiento en las que
            está registrada. Se factura como una unidad `email_social` por
            solicitud, además del precio propio de este endpoint.
          example: true
    EmailRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            ID de la sesión de API creada para esta solicitud. Guárdalo junto
            con `vendor_data` si necesitas relacionar el resultado con webhooks
            posteriores o con la actividad en la consola.
        status:
          type: string
          enum:
            - Approved
            - In Review
            - Declined
          description: >-
            Decisión final de esta sesión de API. Normalmente es `Approved`; la
            evaluación de riesgo puede producir `In Review` o `Declined`.
        vendor_data:
          type: string
          nullable: true
          description: >-
            Devuelve el `vendor_data` que enviaste, o `null` si no enviaste
            ninguno.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Devuelve el `metadata` que enviaste, o `null` si no enviaste
            ninguno.
        created_at:
          type: string
          format: date-time
          description: Marca de tiempo de esta respuesta.
        email:
          type: object
          description: >-
            Informe de correo electrónico normalizado, el mismo bloque que usan
            las respuestas de Verificación de correo electrónico.
          required:
            - status
            - email
            - is_breached
            - breaches
            - is_disposable
            - is_undeliverable
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: >-
                Decisión para esta dirección de correo electrónico. Refleja el
                `status` de nivel superior.
            email:
              type: string
              description: La dirección evaluada.
              example: alice@example.com
            is_breached:
              type: boolean
              description: >-
                Si la dirección aparece en una filtración de credenciales
                conocida.
            breaches:
              type: array
              description: >-
                Hasta 5 de las filtraciones conocidas más recientes que
                contienen esta dirección. Array vacío cuando `is_breached` es
                `false`.
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Identificador de la filtración.
                  domain:
                    type: string
                    description: Dominio del servicio filtrado.
                  breach_date:
                    type: string
                    format: date
                    description: Fecha en que se produjo la filtración.
                  breach_emails_count:
                    type: integer
                    description: Número total de cuentas expuestas en la filtración.
                  description:
                    type: string
                    description: >-
                      Descripción legible de la brecha (puede contener marcado
                      HTML).
                  logo_path:
                    type: string
                    description: URL del logotipo del servicio afectado por la filtración.
                  data_classes:
                    type: array
                    items:
                      type: string
                    description: >-
                      Categorías de datos expuestos, en snake_case (p. ej.,
                      `email_addresses`, `passwords`).
                  is_verified:
                    type: boolean
                    description: Si la filtración se ha verificado como legítima.
            is_disposable:
              type: boolean
              description: Si el dominio pertenece a un proveedor de correo desechable.
            is_undeliverable:
              type: boolean
              description: Si se determinó que la dirección no es entregable.
            verification_attempts:
              type: integer
              description: >-
                Envíos de OTP para esta dirección. `0` en las consultas de
                riesgo.
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                Cuándo se verificó la dirección por última vez mediante un OTP.
                `null` para las consultas de riesgo.
            warnings:
              type: array
              description: >-
                Advertencias de riesgo registradas para esta solicitud. Array
                vacío cuando no hay ninguna.
              items:
                $ref: '#/components/schemas/RiskWarning'
            lifecycle:
              type: array
              description: >-
                Registro de auditoría cronológico de la solicitud. Array vacío
                para consultas de riesgo sin envíos.
              items:
                $ref: '#/components/schemas/RiskLifecycleEvent'
            matches:
              type: array
              description: >-
                Otras sesiones de tu aplicación en las que un usuario distinto
                (con un `vendor_data` diferente) usó la misma dirección de
                correo electrónico. Hasta 5 entradas. Array vacío cuando no hay
                coincidencias.
              items:
                $ref: '#/components/schemas/EmailMatchItem'
            email_intelligence:
              $ref: '#/components/schemas/EmailIntelligence'
            enrichment:
              $ref: '#/components/schemas/EmailIntelligence'
            email_social:
              $ref: '#/components/schemas/EmailSocialFootprint'
    RiskSignals:
      type: object
      description: >-
        Contexto opcional de dispositivo y red observado por tu aplicación.
        Todos los campos son opcionales. Enviarlos alimenta la detección de
        coincidencias entre sesiones en Networks.
      properties:
        ip:
          type: string
          format: ip
          description: Dirección IPv4 o IPv6 observada para el usuario final.
          example: 192.0.2.1
        device_id:
          type: string
          maxLength: 255
          description: >-
            Identificador estable del dispositivo recopilado por tu aplicación
            (`ANDROID_ID` en Android, `identifierForVendor` en iOS).
        device_platform:
          type: string
          enum:
            - android
            - ios
            - ipados
            - tvos
            - web
          description: Plataforma del dispositivo del usuario final.
        device_model:
          type: string
          maxLength: 255
          description: Modelo del dispositivo que informa tu aplicación.
        os_version:
          type: string
          maxLength: 64
          description: Versión del sistema operativo.
        app_version:
          type: string
          maxLength: 64
          description: Versión de tu aplicación.
        user_agent:
          type: string
          maxLength: 512
          description: User agent del navegador o de la aplicación.
    RiskWarning:
      type: object
      required:
        - feature
        - risk
        - log_type
        - short_description
        - long_description
      properties:
        feature:
          type: string
          description: Función que generó la advertencia.
        risk:
          type: string
          description: >-
            Código de riesgo legible por máquina. Con el tiempo pueden añadirse
            nuevos valores.
        additional_data:
          type: object
          nullable: true
          additionalProperties: true
          description: Contexto específico del riesgo, o `null`.
        log_type:
          type: string
          enum:
            - error
            - warning
            - information
          description: Gravedad que usan las reglas de decisión.
        short_description:
          type: string
          description: Resumen legible de una línea.
        long_description:
          type: string
          description: Explicación legible.
    RiskLifecycleEvent:
      type: object
      required:
        - type
        - timestamp
        - details
        - fee
      properties:
        type:
          type: string
          description: >-
            Tipo de evento legible por máquina. Se pueden añadir nuevos valores
            con el tiempo.
        timestamp:
          type: string
          format: date-time
          description: Cuándo ocurrió el evento.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: Payload específico del evento, o `null`.
        fee:
          type: number
          description: Importe en USD facturado por este evento.
    EmailMatchItem:
      type: object
      description: >-
        Otra sesión de tu aplicación que usó la misma dirección de correo
        electrónico con un `vendor_data` distinto.
      properties:
        session_id:
          type: string
          format: uuid
          description: >-
            ID de sesión de la otra verificación que usó esta dirección de
            correo electrónico.
        session_number:
          type: integer
          description: Número secuencial legible de esa sesión.
        vendor_data:
          type: string
          nullable: true
          description: '`vendor_data` de esa sesión.'
        verification_date:
          type: string
          description: Cuándo se creó esa sesión (`YYYY-MM-DDTHH:MM:SSZ`).
        email:
          type: string
          description: La dirección de correo electrónico que coincidió.
        status:
          type: string
          description: >-
            Estado de esa sesión (p. ej., `Approved`, `Declined`, `In
            Progress`).
        is_blocklisted:
          type: boolean
          description: >-
            Si la dirección de correo electrónico está en la lista de bloqueo de
            tu aplicación.
        api_service:
          type: string
          nullable: true
          description: >-
            En las sesiones de tipo API, la API independiente que la creó;
            `null` en las sesiones de verificación normales.
        source:
          type: string
          description: >-
            Dónde se encontró la coincidencia. Normalmente `session`; una
            coincidencia en la lista de bloqueo a través de una entrada de lista
            de la organización usa `list_entry`.
    EmailIntelligence:
      type: object
      description: >-
        Bloque normalizado de inteligencia de correo electrónico. Solo está
        presente cuando el complemento de inteligencia se ejecutó para este
        correo; cuando está presente, también se expone con el alias
        `enrichment` y valores idénticos.
      properties:
        score:
          type: number
          nullable: true
          description: >-
            Puntuación de riesgo normalizada de 0 a 100. Cuanto más alta, mayor
            es el riesgo.
        deliverable:
          type: string
          nullable: true
          description: Rango de entregabilidad (p. ej., `high`).
        breach_risk_level:
          type: string
          nullable: true
          description: '`Low`, `Medium` o `High`.'
        breach_risk_index:
          type: number
          nullable: true
          description: Índice numérico de riesgo de filtración.
        is_recent_breach:
          type: boolean
          nullable: true
          description: '`true` cuando la dirección aparece en una filtración reciente.'
        is_frequent_breached:
          type: boolean
          nullable: true
          description: '`true` cuando la dirección aparece en muchas filtraciones.'
        is_disposable:
          type: boolean
          nullable: true
          description: '`true` cuando el dominio es un proveedor de correo desechable.'
        is_free_domain:
          type: boolean
          nullable: true
          description: '`true` cuando el dominio es un proveedor de correo gratuito.'
        is_breached:
          type: boolean
          nullable: true
          description: '`true` cuando la dirección aparece en filtraciones conocidas.'
        no_of_breaches:
          type: number
          nullable: true
          description: Número de filtraciones conocidas que contienen la dirección.
        reason_codes:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: >-
                  Identificador estable de Didit para la señal, por ejemplo
                  `IR-5AC67A32`. Es opaco: agrupa y filtra por él, pero no lo
                  analices.
              value:
                nullable: true
                description: >-
                  En un indicador de riesgo (por ejemplo, `voip`, `leaked`,
                  `disposable`, `spam_trap`), su valor: un booleano, un nivel o
                  una fecha. Null en un código de motivo con puntuación.
              direction:
                type: string
                enum:
                  - risk
                  - trust
                description: Si la señal aumentó el riesgo o aportó confianza.
              message:
                type: string
                description: Explicación legible de la señal, en inglés.
              impact_level:
                type: string
                nullable: true
                description: >-
                  Cuánto movió la señal la puntuación, por ejemplo `low`,
                  `medium` o `high`.
          description: >-
            Señales que explican la puntuación, cada una con un código estable
            de Didit, una dirección, un mensaje y un nivel de impacto. Pueden
            aparecer códigos nuevos con el tiempo, así que no rechaces los
            códigos desconocidos.
    EmailSocialFootprint:
      type: object
      nullable: true
      description: >-
        Huella social de la dirección de correo electrónico: las plataformas en
        línea en las que está registrada. Solo está presente cuando se activó
        `enable_social` y la comprobación finalizó. Cualquier recuento puede ser
        null cuando no se obtuvieron datos para él. `profiles_registered: 0`
        significa que se comprobaron las plataformas y que la dirección de
        correo electrónico no se encontró en ninguna de ellas: es una respuesta
        válida y facturable, y una señal habitual de identidad sintética.
      properties:
        profiles_registered:
          type: integer
          nullable: true
          description: >-
            Plataformas en las que se ha confirmado que la dirección de correo
            electrónico está registrada.
          example: 5
        profiles_checked:
          type: integer
          nullable: true
          description: Plataformas evaluadas para el registro.
          example: 14
        names_found:
          type: integer
          nullable: true
          description: Plataformas que devolvieron un nombre asociado.
          example: 0
        photos_found:
          type: integer
          nullable: true
          description: Plataformas que devolvieron una foto de perfil.
          example: 0
        communication_breadth:
          type: integer
          nullable: true
          description: Plataformas de comunicación en las que se detectó presencia.
          example: 2
        digital_footprint_diversity:
          type: integer
          nullable: true
          description: Categorías de plataforma distintas en las que se detectó presencia.
          example: 5
        digital_sophistication_index:
          type: integer
          nullable: true
          description: Indicador compuesto de madurez digital, de 0 a 10.
          example: 5
        engagement_depth_index:
          type: integer
          nullable: true
          description: Indicador de riqueza del perfil, de 0 a 10.
          example: 3
        subscription_affordability_index:
          type: integer
          nullable: true
          description: Proporción entre plataformas gratuitas y de pago, de 0 a 10.
          example: 2
        free_platforms:
          type: integer
          nullable: true
          description: Registros en plataformas gratuitas.
          example: 4
        full_paid_platforms:
          type: integer
          nullable: true
          description: Registros en plataformas totalmente de pago.
          example: 0
        partial_paid_platforms:
          type: integer
          nullable: true
          description: Registros en plataformas freemium.
          example: 1
        whatsapp_profile_completeness:
          type: string
          nullable: true
          enum:
            - Basic
            - Partial
            - Complete
            - Not Present
            - null
          description: >-
            Grado de completitud del perfil de WhatsApp. Solo para teléfono;
            null para correo electrónico.
          example: Partial
        registered_platforms:
          type: array
          description: Plataformas en las que se ha confirmado el registro.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        not_registered_platforms:
          type: array
          description: Plataformas comprobadas con resultado negativo.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        categories:
          type: object
          description: Número de registros y proporción por categoría de plataforma.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintCategorySummary'
        profiles:
          type: object
          description: >-
            Detalles del perfil por plataforma, indexados por plataforma, cuando
            la plataforma los expone.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintProfile'
    SocialFootprintPlatform:
      type: object
      properties:
        platform:
          type: string
          description: Identificador de la plataforma.
          example: whatsapp
        category:
          type: string
          description: >-
            Categoría de la plataforma, por ejemplo MESSAGING, SOCIAL_MEDIA,
            ECOMMERCE, PROFESSIONAL, EMAIL_PROVIDER.
          example: MESSAGING
        scope:
          type: string
          enum:
            - global
            - local
          description: >-
            `global` para plataformas de alcance mundial, `local` para las
            específicas de una región.
          example: global
    SocialFootprintCategorySummary:
      type: object
      properties:
        registered:
          type: integer
          nullable: true
          description: >-
            Plataformas de esta categoría en las que se ha confirmado el
            registro.
          example: 2
        ratio:
          type: number
          format: float
          nullable: true
          description: >-
            Proporción de las plataformas comprobadas de la categoría en las que
            existe un registro, de 0.0 a 1.0.
          example: 0.6667
    SocialFootprintProfile:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Nombre del perfil, cuando la plataforma lo expone.
        photo:
          type: string
          nullable: true
          description: URL de la foto del perfil, cuando la plataforma la expone.
        about:
          type: string
          nullable: true
          description: >-
            Texto de presentación o biografía del perfil, cuando la plataforma
            lo expone.
        privacy_status:
          type: string
          nullable: true
          enum:
            - PUBLIC
            - PRIVATE
            - null
          description: Visibilidad del perfil, cuando la plataforma la expone.
        business_account:
          type: boolean
          nullable: true
          description: >-
            Si el perfil es una cuenta de empresa, cuando la plataforma lo
            expone.
  responses:
    EmailRiskValidationError:
      description: Falló la validación de la solicitud.
      content:
        application/json:
          examples:
            Missing email:
              summary: Falta el correo electrónico
              value:
                email:
                  - This field is required.
            Invalid email:
              summary: Correo electrónico no válido
              value:
                email:
                  - Enter a valid email address.
            Invalid country hint:
              summary: Indicación de país no válida
              value:
                country_code:
                  - Ensure this field has no more than 3 characters.
    RiskPermissionDenied:
      description: >-
        Falta la clave de API o no es válida, o la organización no puede cubrir
        la consulta en tiempo real. Esta API nunca devuelve `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              summary: >-
                Falta el encabezado `x-api-key`, o la clave no es válida o está
                revocada
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              summary: El saldo de la organización no cubre el precio de la consulta
              value:
                error: You don't have enough credits to perform this request.
    RateLimitedWrite:
      description: >-
        Se superó el límite de escritura compartido de 300 solicitudes por
        minuto por clave de API. Respeta `Retry-After` antes de reintentar.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  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.