> ## 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 telefónico: operador y señales de fraude

> Didit puntúa el riesgo de un número de teléfono sin enviar OTP: operador, tipo de línea, portabilidad, números desechables y fraude en una llamada.

Usa `POST /v3/phone/risk/` cuando necesites inteligencia telefónica antes de un flujo de OTP, en su lugar o fuera de él.

No envía ningún código al usuario. Crea una sesión de API, enriquece el número, aplica tus reglas de riesgo telefónico y devuelve, en una única respuesta síncrona, el mismo bloque de teléfono normalizado que usa la Phone Verification.

Cuando la solicitud se guarda, Didit también puede usar el número de teléfono evaluado como evidencia agregada en **Networks**. Los grafos de red pueden mostrar inteligencia telefónica de alto riesgo y contexto de portabilidad y tipo de línea en las señales telefónicas compartidas, pero no revelan el número de teléfono sin procesar a otras organizaciones.

## 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`.
* `phone.full_number` es el número normalizado en formato E.164. `phone.phone_number_prefix` y `phone.phone_number` lo dividen en el prefijo internacional y el número nacional.
* `phone.is_disposable` y `phone.is_virtual` son las señales estables de sí/no para la lógica de tu aplicación. La consulta del operador añade `carrier.name` y `carrier.type` (`mobile`, `voip` y similares).
* `phone.phone_intelligence.score` usa una escala de riesgo de 0 a 100 en la que un número más alto significa mayor riesgo. `phone_type_risk` (`Low`, `Medium`, `High`) y `phone_trust_index` (el inverso de la puntuación) son vistas derivadas.
* `phone.phone_intelligence` y `phone.enrichment` son alias de compatibilidad con el mismo objeto normalizado. Las nuevas integraciones pueden leer `phone.enrichment`.
* `phone.matches` enumera otras sesiones de tu aplicación en las que un usuario distinto usó el mismo número. Ú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]
>
> `phone.phone_intelligence` y `phone.enrichment` son campos proporcionados en la medida de lo posible. Una consulta completada puede omitir ambos cuando no se devuelven datos de inteligencia utilizables para ese número, país o plan. Basa primero tus reglas en los campos normalizados estables 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 `phone_social` a la respuesta dentro de `phone`: las plataformas en línea en las que está registrado este número de teléfono, agrupadas por categoría, con los recuentos resumidos y los detalles de perfil que devuelvan nuestros socios de datos.

* `phone.phone_social.profiles_registered` y `phone.phone_social.profiles_checked` son las cifras principales: las plataformas en las que se ha confirmado que el número de teléfono está registrado, del total de plataformas evaluadas.
* `phone.phone_social.registered_platforms` y `phone.phone_social.not_registered_platforms` enumeran cada plataforma con su `category` y su `scope` (`global`, o `local` para plataformas específicas de una región).
* `phone.phone_social.categories` ofrece el recuento de registros y la proporción por categoría, y `phone.phone_social.profiles` incluye los detalles de perfil por plataforma cuando la 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: las plataformas se comprobaron y el número de teléfono no se encontró en ninguna, lo que es una señal habitual de identidad sintética. Este endpoint no toma ninguna medida por sí solo: usa `phone_no_social_presence_action` en un flujo de verificación (workflow) para convertirlo en un veredicto de revisión o de rechazo.

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

## Comportamiento en sandbox

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

## Facturación

Las llamadas a la Phone Risk API cuestan \$0.04 según el precio de lista, menos que la Verificación de teléfono completa porque no se envía ningún OTP. Una solicitud en producción es facturable en cuanto empieza 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 `phone_social` por solicitud, además del precio de la Phone Risk API, siempre que la comprobación se complete. La verificación de créditos previa a la consulta cubre ambos.


## OpenAPI

````yaml es/openapi-25.json POST /v3/phone/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/phone/risk/:
    post:
      tags:
        - Standalone APIs
      summary: Calcular la puntuación de riesgo de un número de teléfono
      description: >-
        Resuelve un número de teléfono y devuelve señales de operador, tipo de
        línea, portabilidad, número desechable, coincidencias entre sesiones e
        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 replica `phone.status`.
        Normalmente es `Approved`; la evaluación de riesgo puede dar como
        resultado `In Review` o `Declined`.


        **Alias de compatibilidad.** Las respuestas en producción exponen el
        objeto de inteligencia normalizado tanto en `phone.phone_intelligence`
        como en `phone.enrichment`. Los valores son idénticos. Las integraciones
        nuevas pueden leer `phone.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 Phone
        Risk API. La solicitud se factura 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 un OTP, 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`. Las credenciales ausentes o no válidas devuelven `403`;
        esta API nunca devuelve `401`.


        **Límite de solicitudes.** Presupuesto 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 `phone_social`: las plataformas en línea en las que está
        registrado este número, con recuentos por categoría y los detalles de
        perfil disponibles. `profiles_registered: 0` significa que se
        comprobaron las plataformas y el número no se encontró en ninguna de
        ellas, 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
        `phone_social` por solicitud además del precio propio de este endpoint.
      operationId: post_v3phone_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneRiskRequest'
            examples:
              Minimal:
                summary: Puntuar un número con los valores predeterminados
                value:
                  phone_number: '+14155552671'
              Full context:
                summary: >-
                  Puntuar con señales, indicación de país e identificadores de
                  correlación
                value:
                  phone_number: '+14155552671'
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: ios
                    device_model: iPhone17,2
                    os_version: 18.0.1
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0
                      Mobile/15E148 Safari/604.1
                  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/PhoneRiskResponse'
              examples:
                Clean mobile number:
                  summary: Número móvil limpio con cobertura de inteligencia
                  value:
                    request_id: 4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62
                    status: Approved
                    phone:
                      status: Approved
                      phone_number_prefix: '+1'
                      phone_number: '4155552671'
                      full_number: '+14155552671'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: Example Mobile
                        type: mobile
                      is_disposable: false
                      is_virtual: false
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                      enrichment:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Number in review:
                  summary: Número desechable o virtual marcado para revisión
                  value:
                    request_id: 8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f
                    status: In Review
                    phone:
                      status: In Review
                      phone_number_prefix: '+44'
                      phone_number: '7700900123'
                      full_number: '+447700900123'
                      country_code: GB
                      country_name: United Kingdom
                      carrier:
                        name: Example VoIP
                        type: voip
                      is_disposable: true
                      is_virtual: true
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                      enrichment:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - code: IR-5AC67A32
                            direction: risk
                            message: Phone type identified as non-mobile
                            impact_level: medium
                    vendor_data: lead-124
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/PhoneRiskValidationError'
        '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/phone/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "phone_number": "+14155552671",
                "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.phone.assess_risk(
                phone_number="+14155552671",
            )
            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.phone.assessRisk({
              phone_number: "+14155552671",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{\n\tPhoneNumber: \"+14155552671\",\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.PhoneRiskRequest;

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

            var result = client.phone().assessRisk(PhoneRiskRequest.builder()
                    .phoneNumber("+14155552671")
                    .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->phone->assessRisk([
                'phone_number' => '+14155552671',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.phone.assess_risk(phone_number: "+14155552671")
            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.Phone.AssessRiskAsync(new PhoneRiskRequest
            {
                PhoneNumber = "+14155552671",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    PhoneRiskRequest:
      type: object
      required:
        - phone_number
      properties:
        phone_number:
          type: string
          maxLength: 20
          description: >-
            Número de teléfono que se va a puntuar. Se valida y se normaliza a
            E.164.
          example: '+14155552671'
        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 del número: las
            plataformas de mensajería, redes sociales, comercio electrónico y
            profesionales en las que está registrado. Se factura como una unidad
            `phone_social` por solicitud, además del precio propio de este
            endpoint.
          example: true
    PhoneRiskResponse:
      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.
        phone:
          type: object
          description: >-
            Informe de teléfono normalizado, el mismo bloque que usan las
            respuestas de Verificación de teléfono.
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: >-
                Decisión para este número de teléfono. Refleja el `status` de
                nivel superior.
            phone_number_prefix:
              type: string
              description: Código telefónico del país con `+` inicial (por ejemplo, `+1`).
              example: '+1'
            phone_number:
              type: string
              description: Número nacional sin el prefijo telefónico del país.
              example: '4155552671'
            full_number:
              type: string
              description: Número completo en formato E.164.
              example: '+14155552671'
            country_code:
              type: string
              nullable: true
              description: País ISO 3166-1 alpha-2 del número.
              example: US
            country_name:
              type: string
              description: Nombre completo del país derivado de `country_code`.
              example: United States
            carrier:
              type: object
              nullable: true
              description: >-
                Red actual que da servicio al número. `null` cuando la consulta
                no pudo identificar un operador.
              properties:
                name:
                  type: string
                  description: >-
                    Nombre del operador. Cadena vacía cuando la consulta no pudo
                    identificarlo.
                type:
                  type: string
                  description: >-
                    Tipo de línea que devuelve la consulta: `mobile`,
                    `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`,
                    `premium_rate` o similares.
            is_disposable:
              type: boolean
              description: >-
                `true` cuando el número pertenece a un servicio de números
                temporales o desechables.
            is_virtual:
              type: boolean
              description: >-
                `true` cuando el tipo de línea es virtual (`voip`, `isp` o
                `vpn`).
            verification_method:
              type: string
              nullable: true
              description: >-
                Canal OTP de la verificación subyacente. `null` en las consultas
                de riesgo, que nunca envían un código.
            verification_attempts:
              type: integer
              description: Envíos de OTP para este número. `0` en las consultas de riesgo.
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                Fecha y hora en que el número se verificó por última vez
                mediante un OTP. `null` para 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 eventos de envío.
              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ó el mismo número de
                teléfono. Hasta 5 entradas. Array vacío cuando no hay
                coincidencias.
              items:
                $ref: '#/components/schemas/PhoneMatchItem'
            phone_intelligence:
              $ref: '#/components/schemas/PhoneIntelligence'
            enrichment:
              $ref: '#/components/schemas/PhoneIntelligence'
            phone_social:
              $ref: '#/components/schemas/PhoneSocialFootprint'
    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.
    PhoneMatchItem:
      type: object
      description: >-
        Otra sesión de tu aplicación que usó el mismo número de teléfono con un
        `vendor_data` distinto.
      properties:
        session_id:
          type: string
          format: uuid
          description: >-
            ID de sesión de la otra verificación que usó este número de
            teléfono.
        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`).
        phone_number:
          type: string
          description: El número de teléfono que coincidió.
        status:
          type: string
          description: >-
            Estado de esa sesión (p. ej., `Approved`, `Declined`, `In
            Progress`).
        is_blocklisted:
          type: boolean
          description: >-
            Si el número de teléfono 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`.
    PhoneIntelligence:
      type: object
      description: >-
        Bloque normalizado de inteligencia telefónica. Solo está presente cuando
        el complemento de inteligencia se ejecutó para esta consulta; 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.
        phone_type_risk:
          type: string
          nullable: true
          description: '`Low`, `Medium` o `High`, según la puntuación.'
        phone_trust_index:
          type: number
          nullable: true
          description: >-
            Inverso de la puntuación, para paneles en los que un valor más alto
            es mejor.
        network_stability_index:
          type: number
          nullable: true
          description: Estabilidad de la red de la línea.
        is_disposable:
          type: boolean
          nullable: true
          description: '`true` cuando el número parece desechable o virtual.'
        is_ported:
          type: boolean
          nullable: true
          description: '`true` cuando el número ha cambiado de operador.'
        is_recently_ported:
          type: boolean
          nullable: true
          description: '`true` cuando la portabilidad se produjo recientemente.'
        carrier_type:
          type: string
          nullable: true
          description: >-
            Clasificación de la línea que devuelve la consulta (p. ej.,
            `mobile`).
        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.
    PhoneSocialFootprint:
      type: object
      nullable: true
      description: >-
        Huella social del número de teléfono: las plataformas en línea en las
        que está registrado. 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 el número de teléfono 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 el número de teléfono
            está registrado.
          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:
    PhoneRiskValidationError:
      description: Falló la validación de la solicitud.
      content:
        application/json:
          examples:
            Missing phone number:
              summary: Falta el número de teléfono
              value:
                phone_number:
                  - This field is required.
            Invalid phone number:
              summary: Número de teléfono no válido
              value:
                phone_number:
                  - Invalid phone number provided.
            Invalid signal IP:
              summary: IP de la señal no válida
              value:
                signals:
                  ip:
                    - Enter a valid IPv4 or IPv6 address.
    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.