> ## 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 risc de telèfon: operador i senyals de frau

> Puntua el risc d'un número de telèfon sense enviar OTP. Operador, tipus de línia, portabilitat i senyals de frau en una crida de Didit.

Utilitza `POST /v3/phone/risk/` quan necessitis intel·ligència sobre el telèfon abans, en lloc de, o fora d'un flux OTP.

No envia cap codi a l'usuari. Crea una sessió d'API, enriqueix el número, aplica les regles de risc de telèfon i retorna, en una única resposta síncrona, el mateix bloc de telèfon normalitzat que utilitza la Verificació de telèfon.

Quan la sol·licitud es desa, Didit també pot utilitzar el número de telèfon puntuat com a evidència agregada a **Xarxes**. Els grafs de xarxa poden mostrar intel·ligència telefònica d'alt risc, i context de portabilitat i de tipus de línia sobre senyals de telèfon compartits, però no revelen el número de telèfon original a altres organitzacions.

## Interpreta la resposta

* `status` és la decisió final d'aquesta sessió d'API. Normalment és `Approved`; l'avaluació de risc pot produir `In Review` o `Declined`.
* `phone.full_number` és el número normalitzat en E.164. `phone.phone_number_prefix` i `phone.phone_number` el separen en el prefix internacional i el número nacional.
* `phone.is_disposable` i `phone.is_virtual` són els senyals estables de sí/no per a la lògica de l'aplicació. La consulta d'operador afegeix `carrier.name` i `carrier.type` (`mobile`, `voip` i similars).
* `phone.phone_intelligence.score` utilitza una escala de risc de 0-100, on un número més alt indica un risc més alt. `phone_type_risk` (`Low`, `Medium`, `High`) i `phone_trust_index` (l'invers de la puntuació) són vistes derivades.
* `phone.phone_intelligence` i `phone.enrichment` són àlies de compatibilitat amb el mateix objecte normalitzat. Les integracions noves poden llegir `phone.enrichment`.
* `phone.matches` enumera altres sessions de la vostra aplicació en què el mateix número va ser utilitzat per un usuari diferent. Utilitzeu-ho per detectar comptes duplicats.
* `request_id` és l'identificador de la sessió d'API. Desa'l amb `vendor_data` si necessites correlacionar el resultat amb webhooks posteriors o amb l'activitat de la consola.

> [!WARNING]
>
> `phone.phone_intelligence` i `phone.enrichment` són camps subjectes a disponibilitat. Una consulta completada pot no incloure cap dels dos quan no es retorna cap dada d'intel·ligència utilitzable per a aquest número, país o pla. Construeix les regles primer sobre els camps normalitzats estables i tracta la intel·ligència que falta com a "desconeguda", no com a "segura".

## Complement de petjada social

Estableix `enable_social` a `true` per afegir un bloc `phone_social` a la resposta, dins de `phone`: les plataformes en línia on aquest número de telèfon està registrat, agrupades per categoria, amb els recomptes del resum i els detalls de perfil que retornen els nostres socis de dades.

* `phone.phone_social.profiles_registered` i `phone.phone_social.profiles_checked` són les xifres principals: les plataformes on el número de telèfon consta com a registrat, sobre el total de plataformes avaluades.
* `phone.phone_social.registered_platforms` i `phone.phone_social.not_registered_platforms` enumeren cada plataforma amb la seva `category` i el seu `scope` (`global`, o `local` per a plataformes específiques de cada regió).
* `phone.phone_social.categories` indica el recompte i la proporció de registres per categoria, i `phone.phone_social.profiles` conté els detalls de perfil per plataforma quan una plataforma els exposa (nom, URL de la foto, text de presentació, estat de privacitat, indicador de compte empresarial).
* Els índexs resum (`digital_footprint_diversity`, `digital_sophistication_index`, `engagement_depth_index`, `subscription_affordability_index`) són índexs compostos amb valors de 0 a 10. Qualsevol recompte pot ser `null` quan la comprovació no ha retornat dades per a aquest recompte.

`profiles_registered: 0` és una resposta real, no un error: les plataformes es van comprovar i el número de telèfon no es va trobar en cap d'elles, cosa que és un senyal habitual d'identitat sintètica. Aquest endpoint no actua per si sol sobre aquest resultat; utilitza `phone_no_social_presence_action` en un flux de treball per convertir-lo en un veredicte de revisió o de rebuig.

El bloc no apareix quan `enable_social` no està establert, ni tampoc quan la comprovació de xarxes socials no es va poder completar; en aquest cas no es factura.

## Comportament del sandbox

Les claus de sandbox validen la sol·licitud i retornen dades deterministes amb resultat aprovat. No envien cap OTP, no consumeixen crèdits, no creen cap sessió ni contribueixen a **Xarxes**. Amb `enable_social` establert, també retornen un bloc `phone_social` determinista.

## Facturació

Les crides a la Phone Risk API costen \$0.04 al preu de llista, menys que una Verificació de telèfon completa, perquè no s'envia cap OTP. Una sol·licitud en directe és facturable en el moment que s'inicia la consulta, fins i tot quan alguns camps subjectes a disponibilitat no estan disponibles.

El complement de petjada social es factura per separat: una unitat `phone_social` per sol·licitud, a més del preu de la Phone Risk API, sempre que la comprovació es completi. La verificació de crèdit prèvia a la consulta cobreix tots dos conceptes.


## OpenAPI

````yaml ca/openapi-25.json POST /v3/phone/risk/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/phone/risk/:
    post:
      tags:
        - Standalone APIs
      summary: Calcular la puntuació de risc d'un número de telèfon
      description: >-
        Resol un número de telèfon i retorna l'operador, el tipus de línia, la
        portabilitat, si és un número d'un sol ús, la coincidència entre
        sessions i senyals d'intel·ligència de risc normalitzats sense enviar
        cap OTP. L'endpoint crea una sessió d'API i en retorna l'id com a
        `request_id`.


        **Decisió.** L'estat `status` de nivell superior reflecteix
        `phone.status`. Normalment és `Approved`; l'avaluació de risc pot
        generar `In Review` o `Declined`.


        **Àlies de compatibilitat.** Les respostes de producció exposen
        l'objecte d'intel·ligència normalitzat tant com a
        `phone.phone_intelligence` com a `phone.enrichment`. Els valors són
        idèntics. Les noves integracions poden llegir `phone.enrichment`.
        Ambdues claus són absents quan no s'han retornat dades d'intel·ligència
        utilitzables.


        **Facturació.** Les crides a producció utilitzen els preus de l'API de
        Phone Risk. La sol·licitud és facturable un cop comença la cerca, fins i
        tot quan alguns camps de millor esforç no estan disponibles.


        **Sandbox.** Les claus de sandbox validen la sol·licitud i retornen
        dades deterministes aprovades sense enviar cap OTP, consumir crèdits,
        crear una sessió ni contribuir a Networks.


        **Autenticació.** Envia la clau d'API de la teva aplicació a
        `x-api-key`. Si les credencials són absents o no vàlides, es retorna
        `403` - aquesta API no retorna mai `401`.


        **Límit de freqüència.** Pressupost d'escriptura compartit de 300
        sol·licituds per minut per clau d'API en els endpoints POST/PATCH/DELETE
        (la creació de transaccions i la ingesta d'esdeveniments tenen un
        pressupost separat de 600).


        **Petjada social.** Estableix `enable_social` a `true` per afegir un
        bloc `phone_social`: les plataformes en línia on està registrat aquest
        número, amb recomptes per categoria i els detalls de perfil disponibles.
        `profiles_registered: 0` significa que s'han consultat les plataformes i
        el número no s'ha trobat en cap d'elles - una resposta vàlida i
        facturable. El bloc és absent quan no s'ha sol·licitat el complement o
        no s'ha pogut completar la comprovació, i en aquest cas no es factura.
        La facturació afegeix una unitat de `phone_social` per sol·licitud a
        sobre del preu propi d'aquest endpoint.
      operationId: post_v3phone_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneRiskRequest'
            examples:
              Minimal:
                summary: Puntua un número amb els valors per defecte
                value:
                  phone_number: '+14155552671'
              Full context:
                summary: >-
                  Puntua amb senyals, indicació de país i identificadors de
                  correlació
                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: >-
            S'ha completat l'avaluació de risc. Inspecciona `status` per
            conèixer la decisió; la resposta HTTP sempre és `200` per a
            consultes completades.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneRiskResponse'
              examples:
                Clean mobile number:
                  summary: Número de mòbil net amb cobertura d'intel·ligència
                  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 d'un sol ús o virtual marcat per a revisió
                  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èfon a puntuar. Es valida i es normalitza a E.164.
          example: '+14155552671'
        country_code:
          type: string
          maxLength: 3
          description: >-
            Indicació opcional de país ISO 3166-1 alfa-2 o alfa-3 per a la
            cobertura d'intel·ligència.
          example: US
        signals:
          $ref: '#/components/schemas/RiskSignals'
        vendor_data:
          type: string
          description: >-
            La teva referència estable per a aquesta sol·licitud. S'emmagatzema
            a la sessió de l'API i es retorna a la resposta.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Les teves metadades JSON no sensibles. S'emmagatzemen a la sessió de
            l'API i es retornen a la resposta.
        enable_social:
          type: boolean
          default: false
          description: >-
            Quan és cert, també consulta la petjada social del número: les
            plataformes de missatgeria, socials, de comerç electrònic i
            professionals on està registrat. Es factura com una unitat de
            `phone_social` per sol·licitud a més del preu propi d'aquest
            endpoint.
          example: true
    PhoneRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Identificador de la sessió d'API creada per a aquesta sol·licitud.
            Emmagatzema'l amb `vendor_data` si necessites correlacionar el
            resultat amb webhooks posteriors o amb l'activitat a la consola.
        status:
          type: string
          enum:
            - Approved
            - In Review
            - Declined
          description: >-
            Decisió final per a aquesta sessió d'API. Normalment `Approved`;
            l'avaluació de risc pot generar `In Review` o `Declined`.
        vendor_data:
          type: string
          nullable: true
          description: >-
            Ressò de les `vendor_data` que has enviat, `null` si no n'has enviat
            cap.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Ressò de les `metadata` que has enviat, `null` si no n'has enviat
            cap.
        created_at:
          type: string
          format: date-time
          description: Marca de temps d'aquesta resposta.
        phone:
          type: object
          description: >-
            Informe normalitzat de telèfon, el mateix bloc utilitzat per les
            respostes de Verificació de telèfon.
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: >-
                Decisió per a aquest número de telèfon. Reflecteix el camp
                `status` de nivell superior.
            phone_number_prefix:
              type: string
              description: Codi telefònic de país que comença amb `+` (p. ex., `+1`).
              example: '+1'
            phone_number:
              type: string
              description: Número nacional sense el prefix telefònic del país.
              example: '4155552671'
            full_number:
              type: string
              description: Número complet en format 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: Nom complet del país derivat de `country_code`.
              example: United States
            carrier:
              type: object
              nullable: true
              description: >-
                Xarxa actual que dona servei al número. `null` quan la cerca no
                ha pogut resoldre cap operador.
              properties:
                name:
                  type: string
                  description: >-
                    Nom de l'operador. Cadena buida quan la cerca no l'ha pogut
                    identificar.
                type:
                  type: string
                  description: >-
                    Tipus de línia indicat per la cerca: `mobile`, `fixed_line`,
                    `voip`, `isp`, `vpn`, `toll_free`, `premium_rate` o similar.
            is_disposable:
              type: boolean
              description: >-
                `true` quan el número pertany a un servei de números temporals o
                d'un sol ús.
            is_virtual:
              type: boolean
              description: >-
                `true` quan el tipus de línia és virtual (`voip`, `isp` o
                `vpn`).
            verification_method:
              type: string
              nullable: true
              description: >-
                Canal d'OTP de la verificació subjacent. `null` per a consultes
                de risc, que mai no envien cap codi.
            verification_attempts:
              type: integer
              description: >-
                Enviaments d'OTP per a aquest número. `0` per a consultes de
                risc.
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                Quan es va verificar el número per darrera vegada mitjançant un
                OTP. `null` per a cerques de risc.
            warnings:
              type: array
              description: >-
                Advertències de risc registrades per a aquesta sol·licitud.
                Matriu buida si no n'hi ha cap.
              items:
                $ref: '#/components/schemas/RiskWarning'
            lifecycle:
              type: array
              description: >-
                Traça d'auditoria cronològica de la sol·licitud. Matriu buida
                per a cerques de risc sense esdeveniments d'enviament.
              items:
                $ref: '#/components/schemas/RiskLifecycleEvent'
            matches:
              type: array
              description: >-
                Altres sessions de la teva aplicació on un usuari diferent (amb
                un `vendor_data` diferent) ha utilitzat el mateix número de
                telèfon. Fins a 5 entrades. Matriu buida quan no hi ha
                coincidències.
              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: >-
        Context opcional de dispositiu i xarxa observat per la teva aplicació.
        Tots els camps són opcionals. Enviar-los alimenta la detecció de
        coincidències entre sessions a Networks.
      properties:
        ip:
          type: string
          format: ip
          description: Adreça IPv4 o IPv6 observada per a l'usuari final.
          example: 192.0.2.1
        device_id:
          type: string
          maxLength: 255
          description: >-
            Identificador de dispositiu estable recollit per la teva aplicació
            (`ANDROID_ID` a Android, `identifierForVendor` a iOS).
        device_platform:
          type: string
          enum:
            - android
            - ios
            - ipados
            - tvos
            - web
          description: Plataforma del dispositiu de l'usuari final.
        device_model:
          type: string
          maxLength: 255
          description: Model de dispositiu informat per la teva aplicació.
        os_version:
          type: string
          maxLength: 64
          description: Versió del sistema operatiu.
        app_version:
          type: string
          maxLength: 64
          description: Versió de la teva aplicació.
        user_agent:
          type: string
          maxLength: 512
          description: Agent d'usuari del navegador o de l'aplicació.
    RiskWarning:
      type: object
      required:
        - feature
        - risk
        - log_type
        - short_description
        - long_description
      properties:
        feature:
          type: string
          description: Funcionalitat que ha generat l'advertència.
        risk:
          type: string
          description: >-
            Codi de risc llegible per màquina. Es poden afegir nous valors al
            llarg del temps.
        additional_data:
          type: object
          nullable: true
          additionalProperties: true
          description: Context específic del risc, o `null`.
        log_type:
          type: string
          enum:
            - error
            - warning
            - information
          description: Gravetat utilitzada per les regles de decisió.
        short_description:
          type: string
          description: Resum d'una sola línia, llegible per a humans.
        long_description:
          type: string
          description: Explicació fàcil de llegir.
    RiskLifecycleEvent:
      type: object
      required:
        - type
        - timestamp
        - details
        - fee
      properties:
        type:
          type: string
          description: >-
            Tipus d'esdeveniment llegible per màquina. Se'n poden afegir nous
            valors amb el temps.
        timestamp:
          type: string
          format: date-time
          description: Quan va ocórrer l'esdeveniment.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: Payload específic de l'esdeveniment, o `null`.
        fee:
          type: number
          description: Import en USD facturat per aquest esdeveniment.
    PhoneMatchItem:
      type: object
      description: >-
        Una altra sessió de la teva aplicació que ha utilitzat el mateix número
        de telèfon amb un `vendor_data` diferent.
      properties:
        session_id:
          type: string
          format: uuid
          description: >-
            ID de sessió de l'altra verificació que ha utilitzat aquest número
            de telèfon.
        session_number:
          type: integer
          description: Número seqüencial fàcil de llegir d'aquesta sessió.
        vendor_data:
          type: string
          nullable: true
          description: '`vendor_data` d''aquella sessió.'
        verification_date:
          type: string
          description: Quan es va crear aquesta sessió (`YYYY-MM-DDTHH:MM:SSZ`).
        phone_number:
          type: string
          description: El número de telèfon coincident.
        status:
          type: string
          description: >-
            Estat d'aquesta sessió (p. ex., `Approved`, `Declined`, `In
            Progress`).
        is_blocklisted:
          type: boolean
          description: >-
            Si el número de telèfon és a la llista de bloqueig de la teva
            aplicació.
        api_service:
          type: string
          nullable: true
          description: >-
            Per a sessions de tipus API, l'API independent que la va crear;
            `null` per a sessions de verificació habituals.
        source:
          type: string
          description: >-
            On s'ha trobat la coincidència. Normalment `session`; una
            coincidència amb la llista de bloqueig mitjançant una entrada de
            llista de l'organització utilitza `list_entry`.
    PhoneIntelligence:
      type: object
      description: >-
        Bloc d'intel·ligència de telèfon normalitzat. Només present quan el
        complement d'intel·ligència s'ha executat per a aquesta consulta; quan
        és present també s'exposa sota l'àlies `enrichment` amb valors idèntics.
      properties:
        score:
          type: number
          nullable: true
          description: >-
            Puntuació de risc normalitzada de 0 a 100. Com més alta, més
            arriscada.
        phone_type_risk:
          type: string
          nullable: true
          description: '`Low`, `Medium` o `High`, derivat de la puntuació.'
        phone_trust_index:
          type: number
          nullable: true
          description: >-
            Invers de la puntuació, per a taulers que prefereixen que un valor
            més alt sigui millor.
        network_stability_index:
          type: number
          nullable: true
          description: Estabilitat de la xarxa de la línia.
        is_disposable:
          type: boolean
          nullable: true
          description: '`true` quan el número sembla d''un sol ús o virtual.'
        is_ported:
          type: boolean
          nullable: true
          description: '`true` quan el número ha canviat d''operador.'
        is_recently_ported:
          type: boolean
          nullable: true
          description: '`true` quan la portabilitat s''ha produït recentment.'
        carrier_type:
          type: string
          nullable: true
          description: Classificació de la línia indicada per la cerca (p. ex., `mobile`).
        reason_codes:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: >-
                  Identificador estable de Didit del senyal, per exemple
                  `IR-5AC67A32`. Opac: agrupa i filtra per ell, no l'analitzis
                  sintàcticament.
              value:
                nullable: true
                description: >-
                  Per a un indicador de risc (per exemple `voip`, `leaked`,
                  `disposable`, `spam_trap`), el seu valor: un booleà, un nivell
                  o una data. Null per a un codi de motiu amb puntuació.
              direction:
                type: string
                enum:
                  - risk
                  - trust
                description: Si el senyal ha augmentat el risc o ha reforçat la confiança.
              message:
                type: string
                description: Explicació fàcil de llegir del senyal, en anglès.
              impact_level:
                type: string
                nullable: true
                description: >-
                  Amb quina intensitat ha modificat la puntuació el senyal, per
                  exemple `low`, `medium` o `high`.
          description: >-
            Senyals que expliquen la puntuació, cadascun amb un codi de Didit
            estable, una direcció, un missatge i un nivell d'impacte. Poden
            aparèixer codis nous al llarg del temps, de manera que no rebutgis
            els codis desconeguts.
    PhoneSocialFootprint:
      type: object
      nullable: true
      description: >-
        Petjada social del número de telèfon: les plataformes en línia on està
        registrat. Només present si s'ha definit `enable_social` i la
        comprovació s'ha completat. Cada recompte pot ser nul si no s'han
        obtingut dades. `profiles_registered: 0` significa que s'han consultat
        les plataformes i que el número de telèfon no s'ha trobat en cap
        d'elles: una resposta vàlida i facturable, i un senyal habitual
        d'identitat sintètica.
      properties:
        profiles_registered:
          type: integer
          nullable: true
          description: Plataformes on el número de telèfon està confirmat com a registrat.
          example: 5
        profiles_checked:
          type: integer
          nullable: true
          description: Plataformes avaluades per al registre.
          example: 14
        names_found:
          type: integer
          nullable: true
          description: Plataformes que han retornat un nom associat.
          example: 0
        photos_found:
          type: integer
          nullable: true
          description: Plataformes que han retornat una foto de perfil.
          example: 0
        communication_breadth:
          type: integer
          nullable: true
          description: Plataformes de comunicació amb presència detectada.
          example: 2
        digital_footprint_diversity:
          type: integer
          nullable: true
          description: Categories de plataforma diferents amb presència detectada.
          example: 5
        digital_sophistication_index:
          type: integer
          nullable: true
          description: Indicador compost de maduresa digital, 0-10.
          example: 5
        engagement_depth_index:
          type: integer
          nullable: true
          description: Indicador de riquesa del perfil, de 0 a 10.
          example: 3
        subscription_affordability_index:
          type: integer
          nullable: true
          description: Combinació de plataformes gratuïtes i de pagament, 0-10.
          example: 2
        free_platforms:
          type: integer
          nullable: true
          description: Registres en plataformes gratuïtes.
          example: 4
        full_paid_platforms:
          type: integer
          nullable: true
          description: Registres en plataformes totalment de pagament.
          example: 0
        partial_paid_platforms:
          type: integer
          nullable: true
          description: Registres en plataformes freemium.
          example: 1
        whatsapp_profile_completeness:
          type: string
          nullable: true
          enum:
            - Basic
            - Partial
            - Complete
            - Not Present
            - null
          description: >-
            Completitud del perfil de WhatsApp. Només per a telèfon; null per a
            correu electrònic.
          example: Partial
        registered_platforms:
          type: array
          description: Plataformes on el registre està confirmat.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        not_registered_platforms:
          type: array
          description: Plataformes comprovades amb resultat negatiu.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        categories:
          type: object
          description: Recompte registrat i proporció per categoria de plataforma.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintCategorySummary'
        profiles:
          type: object
          description: >-
            Detalls del perfil per plataforma, indexats per plataforma, quan la
            plataforma els exposa.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintProfile'
    SocialFootprintPlatform:
      type: object
      properties:
        platform:
          type: string
          description: Identificador de plataforma.
          example: whatsapp
        category:
          type: string
          description: >-
            Categoria de plataforma, p. ex. MESSAGING, SOCIAL_MEDIA, ECOMMERCE,
            PROFESSIONAL, EMAIL_PROVIDER.
          example: MESSAGING
        scope:
          type: string
          enum:
            - global
            - local
          description: >-
            `global` per a plataformes d'àmbit mundial, `local` per a les
            específiques d'una regió.
          example: global
    SocialFootprintCategorySummary:
      type: object
      properties:
        registered:
          type: integer
          nullable: true
          description: Plataformes d'aquesta categoria on el registre està confirmat.
          example: 2
        ratio:
          type: number
          format: float
          nullable: true
          description: >-
            Proporció de les plataformes comprovades de la categoria amb un
            registre, 0.0-1.0.
          example: 0.6667
    SocialFootprintProfile:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Nom del perfil, quan la plataforma l'exposa.
        photo:
          type: string
          nullable: true
          description: URL de la foto de perfil, quan la plataforma l'exposa.
        about:
          type: string
          nullable: true
          description: Text d'informació/biografia del perfil, quan la plataforma l'exposa.
        privacy_status:
          type: string
          nullable: true
          enum:
            - PUBLIC
            - PRIVATE
            - null
          description: Visibilitat del perfil, quan la plataforma l'exposa.
        business_account:
          type: boolean
          nullable: true
          description: Si el perfil és un compte d'empresa, quan la plataforma l'exposa.
  responses:
    PhoneRiskValidationError:
      description: Ha fallat la validació de la sol·licitud.
      content:
        application/json:
          examples:
            Missing phone number:
              summary: Falta el número de telèfon
              value:
                phone_number:
                  - This field is required.
            Invalid phone number:
              summary: Número de telèfon no vàlid
              value:
                phone_number:
                  - Invalid phone number provided.
            Invalid signal IP:
              summary: IP de senyal no vàlida
              value:
                signals:
                  ip:
                    - Enter a valid IPv4 or IPv6 address.
    RiskPermissionDenied:
      description: >-
        Falta la clau d'API o no és vàlida, o l'organització no pot cobrir la
        consulta en temps real. Aquesta API mai no retorna `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              summary: >-
                Sense capçalera `x-api-key`, o la clau no és vàlida o s'ha
                revocat
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              summary: El saldo de l'organització no pot cobrir el preu de la consulta
              value:
                error: You don't have enough credits to perform this request.
    RateLimitedWrite:
      description: >-
        S'ha superat el límit compartit d'escriptura de 300 sol·licituds per
        minut per clau d'API. Respecta `Retry-After` abans 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 clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau primària té accés complet. Una clau amb nom
        pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
        limitada a determinats fluxos de treball o a sessions aprovades, a una
        llista d'adreces IP i a una data de caducitat. 401 significa que la clau
        és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
        clau, que la clau no té accés a aquest recurs o acció, o que la
        sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
        ruta de sessió significa que la sessió està fora dels fluxos de treball
        o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
        URL d'imatge, vídeo i PDF com a null, i una clau sense permís
        d'escriptura de sessions rep els enllaços de sessió i els tokens com a
        null. Consulta https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.