> ## 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 codi OTP de telèfon: validar codi SMS > POST /v3/phone/check/ per validar un OTP de telèfon amb tipus d'operador, número virtual i detecció de desechables a Didit. Preu per ús, sense mínims mensuals. ## Gestió de les interrupcions del proveïdor Si el proveïdor de telefonia no està disponible temporalment, aquest endpoint retorna `502` amb un codi estable i llegible per màquines: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Tracta aquesta resposta com a reintentable. Fes servir una espera curta abans de reintentar i mostra a l'usuari un missatge de servei temporalment no disponible, en lloc de demanar-li que canviï un número de telèfon o un codi vàlids. ## Complement d'intel·ligència Estableix `enable_enrichment` a `true` per executar també la intel·ligència de telefonia sobre el número: una puntuació de risc, el tipus de línia, si el número s'ha portat recentment a un altre operador i un índex de confiança. El complement es factura a \$0.05 per sol·licitud al preu de llista, a sobre del preu de la verificació. La sol·licitud retorna `403` quan el teu saldo no és suficient per cobrir-lo. Quatre camps determinen què fan els senyals. Cadascun és `NO_ACTION` (el valor per defecte) o `DECLINE`, i cadascun només té efecte quan `enable_enrichment` és `true`. | Camp | Rebutja quan | | - | - | | `phone_intelligence_score_action` | La puntuació de risc és superior al llindar. | | `phone_type_risk_action` | El número és d'un tipus de línia d'alt risc. | | `recent_port_action` | El número s'ha transferit recentment a un altre operador. | | `low_phone_trust_action` | L'índex de confiança és igual o inferior al llindar. | Amb `NO_ACTION`, el senyal es retorna igualment a `phone.phone_intelligence`, perquè puguis aplicar la teva pròpia regla. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/phone/check/ 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/check/: post: tags: - Standalone APIs summary: Comprovar el codi de telèfon description: >- Verifica l'OTP lliurat per [`POST /v3/phone/send/`](/ca/standalone-apis/phone-send) i obtén el resultat final de la verificació a més d'informació d'intel·ligència del telèfon: nom de l'operador i tipus de línia, indicadors de número virtual (VoIP) i d'un sol ús, i l'ús duplicat del número entre les teves sessions. **Com es localitza la verificació.** La coincidència es fa mitjançant la teva aplicació i el `phone_number` en format E.164; `request_id` no és un paràmetre d'entrada. Es comprova la verificació pendent més recent creada en els darrers **5 minuts**. Si no n'hi ha cap (no s'ha enviat mai, ja està finalitzada o té més de 5 minuts), l'endpoint retorna `200` amb `status: "Expired or Not Found"`. **Límit d'intents.** Cada verificació permet **3 intents de codi**. Els dos primers codis incorrectes retornen `status: "Failed"` amb els intents restants i `phone: null`; el tercer codi incorrecte finalitza la verificació com a `Declined` amb una advertència `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` i retorna l'informe complet del telèfon. **Resultats.** `Approved` — codi correcte i cap risc que motivi un rebuig. `Declined` — terminal: el codi era correcte però ha coincidit un risc de rebuig (una acció `DECLINE` més avall, un número inclòs a la llista de bloqueig o un número d'alt risc), o bé s'ha esgotat el límit d'intents. `Failed` — codi incorrecte, queden intents. `Expired or Not Found` — res a comprovar. Amb `Approved`/`Declined`, el `request_id` és igual al `request_id` de l'enviament (l'identificador de sessió) i `phone` conté l'informe complet (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); amb `Failed` i `Expired or Not Found`, el `request_id` és un UUID aleatori d'un sol ús. **Accions de risc.** `duplicated_phone_number_action`, `disposable_number_action` i `voip_number_action` decideixen què passa quan es detecta el risc corresponent amb un codi correcte: `DECLINE` canvia l'estat final a `Declined`; `NO_ACTION` (per defecte) registra el risc a `phone.warnings` sense afectar l'estat. **Facturació.** Les comprovacions són gratuïtes; el lliurament es factura en la part de l'enviament (consulta [Preus de la verificació de telèfon](/ca/getting-started/phone-verification-pricing)). **Persistència de la sessió.** Una comprovació finalitzada actualitza la sessió creada per l'enviament (visible a la Business Console, consultable mitjançant `GET /v3/session/{sessionId}/decision/`) i dispara un webhook `status.updated`. **Sandbox.** Les claus d'API de sandbox ometen tot el processament: qualsevol codi ben format (de 4 a 8 xifres, `123456` inclòs) retorna un payload `Approved` estàtic amb un objecte pla `phone` simplificat (`status`, `phone_number`, `country_code`, `carrier_name`, `line_type`, `flags`); una entrada mal formada continua retornant `400`. No es persisteix res. **Autenticació.** Envia la clau d'API de la teva aplicació a la capçalera `x-api-key`. Unes credencials absents o no vàlides retornen `403` (`{"detail": "You do not have permission to perform this action."}`) — aquesta API mai no retorna `401`. **Límits de freqüència.** Pressupost d'escriptura compartit de 300 sol·licituds/min per clau d'API, a més del límit antiabús del sistema ascendent de 4 intents per número i hora; si se supera qualsevol dels dos es retorna `429`. **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 qualsevol detall del perfil disponible. `profiles_registered: 0` significa que s'han comprovat les plataformes i el número no s'ha trobat en cap d'elles: una resposta vàlida i facturable. El bloc no apareix si no s'ha sol·licitat el complement o si la comprovació no s'ha pogut completar, 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_check requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- El mateix número de telèfon utilitzat a la crida [`POST /v3/phone/send/`](/ca/standalone-apis/phone-send) coincident, en format E.164. Això és el que enllaça la comprovació amb l'enviament. example: '+14155552671' code: type: string minLength: 4 maxLength: 8 pattern: ^[0-9]{4,8}$ description: >- L'OTP que ha rebut l'usuari final. Ha de tenir entre 4 i 8 dígits numèrics; qualsevol altra cosa retorna `400` sense consumir cap intent. Un codi ben format però incorrecte retorna `200` amb `status: "Failed"` i consumeix un dels 3 intents. example: '123456' duplicated_phone_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Què fer quan el mateix número ja ha estat utilitzat per un usuari diferent (diferent `vendor_data`) de la teva aplicació. `DECLINE` canvia el `status` final a `Declined`; `NO_ACTION` registra el risc a `phone.warnings` i emplena `phone.matches`. disposable_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Què fer quan la cerca de l'operador marca el número com a línia temporal/d'un sol ús (`phone.is_disposable`). `DECLINE` canvia el `status` final a `Declined`; `NO_ACTION` registra el risc a `phone.warnings`. voip_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Què fer quan la cerca de l'operador indica un tipus de línia virtual — `voip`, `isp` o `vpn` (`phone.is_virtual`). `DECLINE` canvia el `status` final a `Declined`; `NO_ACTION` registra el risc a `phone.warnings`. enable_enrichment: type: boolean default: false description: >- Quan és `true`, també executa intel·ligència telefònica al número: una puntuació de risc, el tipus de línia, si s'ha portat recentment i un índex de confiança. Es factura com una unitat de `phone_intelligence_api` per sol·licitud ($0.05 a preu de tarifa) a més del preu propi d'aquest endpoint. La sol·licitud retorna `403` quan el teu saldo no pot cobrir-ho. example: false phone_intelligence_score_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Acció quan la puntuació de risc de la intel·ligència telefònica supera el llindar. `DECLINE` canvia l'`status` final a `Declined`; `NO_ACTION` registra el senyal sense rebutjar. Només té efecte quan `enable_enrichment` és `true`. phone_type_risk_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Acció quan el número és d'un tipus de línia d'alt risc. `DECLINE` canvia l'`status` final a `Declined`; `NO_ACTION` registra el senyal sense rebutjar. Només té efecte quan `enable_enrichment` és `true`. recent_port_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Acció quan el número s'ha portat recentment a una altra operadora. `DECLINE` canvia l'`status` final a `Declined`; `NO_ACTION` registra el senyal sense rebutjar. Només té efecte quan `enable_enrichment` és `true`. low_phone_trust_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Acció quan l'índex de confiança de la intel·ligència telefònica és igual o inferior al llindar. `DECLINE` canvia l'`status` final a `Declined`; `NO_ACTION` registra el senyal sense rebutjar. Només té efecte quan `enable_enrichment` és `true`. 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 phone_no_social_presence_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Acció quan la comprovació de petjada social no troba el número registrat a cap de les plataformes que cobreix. En aquest endpoint només s'accepten NO_ACTION i DECLINE; REVIEW està disponible a la clau de configuració del flux de treball amb el mateix nom. required: - phone_number - code examples: Default: summary: Registra qualsevol risc però no rebutgis mai automàticament value: phone_number: '+14155552671' code: '123456' Strict risk policy: summary: Rebutja automàticament línies VoIP i d'un sol ús value: phone_number: '+14155552671' code: '123456' voip_number_action: DECLINE disposable_number_action: DECLINE responses: '200': description: >- Comprovació completada: els codis incorrectes i les verificacions que falten també retornen `200`; inspecciona `status`, no el codi HTTP. `phone` només s'emplena en resultats finalitzats (`Approved`/`Declined`), és `null` a `Failed`, i no apareix a `Expired or Not Found`. content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationCheckResponse' examples: Approved: summary: >- Codi correcte — informe complet de telèfon amb operador, cicle de vida i coincidències value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Approved message: The verification code is correct. phone: status: Approved phone_number_prefix: '+1' phone_number: '4155552671' full_number: '+14155552671' country_code: US country_name: United States carrier: name: AT&T type: mobile is_disposable: false is_virtual: false verification_method: whatsapp verification_attempts: 1 verified_at: '2026-06-12T01:24:47.311323Z' warnings: [] lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: whatsapp fee: 0.0509 - type: PHONE_DELIVERY_DELIVERED timestamp: '2026-06-12T01:23:43.118220+00:00' details: channel: whatsapp status: delivered fee: 0 - type: VALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '123456' status: Approved fee: 0 - type: PHONE_VERIFICATION_APPROVED timestamp: '2026-06-12T01:24:47.384292+00:00' details: null fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Failed (attempts remaining): summary: >- Codi incorrecte: l'usuari pot reintentar; request_id aquí és un UUID d'un sol ús value: request_id: 11111111-2222-3333-4444-555555555555 status: Failed message: 'The verification code is incorrect. Attempts remaining: 2' phone: null vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:21.512340+00:00' Declined (max attempts): summary: >- Tercer codi incorrecte: verificació finalitzada com a Rebutjada value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Declined message: >- The verification code is incorrect. Maximum attempts reached. phone: status: Declined phone_number_prefix: '+1' phone_number: '4155552671' full_number: '+14155552671' country_code: US country_name: United States carrier: name: AT&T type: mobile is_disposable: false is_virtual: false verification_method: whatsapp verification_attempts: 1 verified_at: null warnings: - feature: PHONE risk: VERIFICATION_CODE_ATTEMPTS_EXCEEDED additional_data: null log_type: error short_description: Verification code attempts exceeded long_description: >- The system detected that the phone number has exceeded the maximum number of verification code attempts. lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: whatsapp fee: 0.0509 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:01.118220+00:00' details: code_tried: '111111' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:21.512340+00:00' details: code_tried: '222222' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '333333' status: Failed fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VERIFICATION_CODE_ATTEMPTS_EXCEEDED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Declined (risk policy): summary: >- Codi correcte, però la línia és VoIP i voip_number_action=DECLINE value: request_id: 7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a status: Declined message: The verification code is correct. phone: status: Declined phone_number_prefix: '+1' phone_number: '5005550006' full_number: '+15005550006' country_code: US country_name: United States carrier: name: CLEC LLC type: voip is_disposable: false is_virtual: true verification_method: sms verification_attempts: 1 verified_at: '2026-06-12T01:24:47.311323Z' warnings: - feature: PHONE risk: VOIP_NUMBER_DETECTED additional_data: null log_type: error short_description: VoIP number detected long_description: >- The system detected that the phone number is a VoIP number, which is not allowed. lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: sms fee: 0.0509 - type: VALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '123456' status: Approved fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VOIP_NUMBER_DETECTED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Expired or Not Found: summary: >- No hi ha cap verificació pendent per a aquest número en els darrers 5 minuts value: request_id: 69cc35c6-280a-47a6-ab8c-4f32abc02ed0 status: Expired or Not Found message: No pending phone verification found in the last 5 minutes. vendor_data: null metadata: null created_at: '2026-06-12T01:24:47.311323+00:00' '400': description: >- Error de validació — embolcall d'errors de camp de DRF: una matriu de missatges per camp infractor. content: application/json: examples: Invalid code format: summary: '`code` no té entre 4 i 8 dígits numèrics' value: code: - Invalid code format. Enter 4 to 8 numeric digits. Invalid phone number: summary: '`phone_number` no és un E.164 vàlid' value: phone_number: - Invalid phone number provided. Invalid action: summary: Les accions de risc només accepten NO_ACTION o DECLINE value: voip_number_action: - '"REVIEW" is not a valid choice.' '403': description: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key`; una clau incorrecta, revocada o caducada retorna `401`. Les comprovacions són gratuïtes, de manera que aquí no hi ha cap comprovació de crèdit. content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. '429': description: >- S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600). A més, a nivell superior s'aplica un límit contra abusos de 4 intents de verificació per número de telèfon i per hora. La resposta inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` i `Retry-After`. Nota: les capçaleres `X-RateLimit-*`/`Retry-After` només acompanyen l'error 429 del límit d'escriptura de 300/min; el 429 del límit per número de telèfon no conté capçaleres de límit de freqüència. content: application/json: examples: Per-number cap: summary: >- Més de 4 intents de verificació per al mateix número en l'última hora value: detail: >- Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number. Write rate limit exceeded: summary: Més de 300 sol·licituds d'escriptura en el minut actual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '500': description: >- Error inesperat en verificar el codi en el proveïdor que no correspon a una caiguda coneguda del proveïdor. Es pot reintentar amb seguretat; el pressupost d'intents només es consumeix amb les comprovacions completades. content: application/json: examples: Provider error: summary: No s'ha pogut completar la verificació del codi value: detail: Error checking phone verification schema: type: object properties: detail: type: string '502': description: >- El proveïdor de verificació de telèfon no està disponible temporalment: una resposta 5xx, un temps d'espera esgotat o un error de connexió que ha persistit després dels reintents integrats. És segur reintentar-ho; no es consumeix el límit d'intents. content: application/json: examples: Provider outage: summary: El proveïdor no ha respost a la sol·licitud de comprovació value: detail: >- Phone verification is temporarily unavailable. Please try again shortly. code: phone_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/phone/check/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "code": "123456", "voip_number_action": "DECLINE" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.check_code( phone_number="+14155552671", code="123456", ) 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.checkCode({ phone_number: "+14155552671", code: "123456", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tCode: \"123456\",\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.PhoneCheckCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().checkCode(PhoneCheckCodeParams.builder() .phoneNumber("+14155552671") .code("123456") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->checkCode([ 'phone_number' => '+14155552671', 'code' => '123456', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.check_code( phone_number: "+14155552671", code: "123456" ) 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.CheckCodeAsync(new PhoneCheckCodeParams { PhoneNumber = "+14155552671", Code = "123456", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationCheckResponse: type: object properties: request_id: type: string format: uuid description: >- A `Approved`/`Declined`: l'identificador de sessió de la verificació coincident — idèntic al `request_id` retornat per `POST /v3/phone/send/`. A `Failed` i `Expired or Not Found`: un UUID aleatori d'un sol ús que no es podrà consultar posteriorment. status: type: string enum: - Approved - Declined - Failed - Expired or Not Found description: >- `Approved` — codi correcte, sense risc que provoqui rebuig. `Declined` — terminal: ha coincidit un risc que provoca rebuig o s'ha esgotat el pressupost d'intents (3). `Failed` — codi incorrecte, queden intents. `Expired or Not Found` — cap verificació pendent per a aquest número en els darrers 5 minuts. message: type: string description: >- Explicació fàcil de llegir del resultat, inclòs el nombre d'intents restants després d'un codi incorrecte. phone: type: object nullable: true description: >- Informe telefònic complet. Present (no nul) només en resultats finalitzats (`Approved`/`Declined`); `null` a `Failed` i absent en `Expired or Not Found`. properties: status: type: string enum: - Approved - Declined - In Review - Not Finished - Expired description: >- Estat final de la verificació de telèfon. Coincideix amb el `status` de nivell superior per a les comprovacions finalitzades. 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 description: >- Xarxa actual que dona servei al número, a partir de la cerca d'operador executada en finalitzar. 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`, `pager`, `payphone`, `satellite`, `service`, `shared_cost`, `short_codes_commercial`, `calling_cards`, `local_rate`, `universal_access`, `voice_mail`, `other` o `unknown`. is_disposable: type: boolean description: >- `true` quan el número pertany a un servei de números temporals/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 description: >- Canal que realment ha lliurat l'OTP un cop confirmat el lliurament (p. ex., `whatsapp`, `sms`); fins aleshores, el canal sol·licitat. verification_attempts: type: integer description: >- Nombre d'enviaments d'OTP per a aquesta verificació (1, o 2 després d'un reintent). verified_at: type: string format: date-time nullable: true description: >- Quan es va introduir el codi correcte. `null` si la verificació mai no es va aprovar. warnings: type: array description: >- Advertències de risc registrades durant la verificació (duplicate, disposable, VoIP, attempts exceeded, blocklist, etc.). Matriu buida si no n'hi ha cap. items: type: object properties: feature: type: string description: >- Funcionalitat que ha generat l'advertència. Sempre `PHONE` aquí. risk: type: string description: Codi de risc llegible per màquina. additional_data: type: object nullable: true description: >- Context específic del risc (p. ex., l'id de la sessió duplicada per a riscos de duplicats). `null` quan el risc no inclou dades addicionals. log_type: type: string enum: - error - warning - information description: >- Gravetat. Els riscos `error` fan que es rebutgi la verificació, `warning` la marca per a revisió i `information` es registra sense afectar l'estat. short_description: type: string description: Resum d'una sola línia del risc, llegible per a humans. long_description: type: string description: Explicació fàcil de llegir del risc. lifecycle: type: array description: >- Pista d'auditoria cronològica de la verificació. El `type` de l'esdeveniment és un dels següents: `PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`, `PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `PHONE_VERIFICATION_APPROVED`, `PHONE_VERIFICATION_DECLINED`, `PHONE_VERIFICATION_IN_REVIEW`, `PHONE_VERIFICATION_EXPIRED`. items: type: object properties: type: type: string description: Tipus d'esdeveniment. timestamp: type: string format: date-time description: Quan va ocórrer l'esdeveniment. details: type: object nullable: true description: >- Payload específic de l'esdeveniment. Esdeveniments d'enviament: `{status, reason, channel, actual_channel}` (`actual_channel` s'omple un cop confirmat el lliurament). Esdeveniments de lliurament: `{channel, status}`. Esdeveniments d'introducció de codi: `{code_tried, status}`. Esdeveniments d'estat final: `null`, o `{reason}` si s'ha rebutjat o està en revisió. fee: type: number description: >- Import en USD facturat per aquest esdeveniment. Diferent de zero només en els esdeveniments d'enviament (el preu de lliurament); 0 per a entrades de codi, confirmacions de lliurament i esdeveniments d'estat. matches: type: array description: >- Altres sessions de la teva aplicació (KYC, KYB o API) on un usuari diferent (amb un `vendor_data` diferent) ha utilitzat el mateix número de telèfon. Fins a 5 entrades, primer una coincidència sintètica d'una entrada de la llista de bloqueig quan n'hi hagi (les coincidències derivades de sessions mantenen l'ordre de la consulta). Matriu buida quan no hi ha coincidències. items: type: object 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 (p. ex., `PHONE_VERIFICATION`); `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ó anteposa una coincidència sintètica amb `source: "list_entry"` i `session_id`/`session_number` nuls. phone_social: $ref: '#/components/schemas/PhoneSocialFootprint' phone_intelligence: allOf: - $ref: '#/components/schemas/PhoneIntelligence' description: >- Senyals d'intel·ligència telefònica. Present només quan `enable_enrichment` era `true` a la comprovació. vendor_data: type: string nullable: true description: >- `vendor_data` de la sessió de la verificació coincident. `null` a `Expired or Not Found`. metadata: type: object nullable: true description: >- `metadata` de la sessió de la verificació coincident. `null` a `Expired or Not Found`. created_at: type: string format: date-time description: Marca de temps de la resposta d'aquesta comprovació. 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' 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. 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. 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.