{"openapi":"3.0.0","paths":{"/sdk-api/phone-verification/create-session/v1.0.0":{"post":{"description":"Create a verification session for the SDK using the configuration of the API Key provide as credentials. It can be further customized by passing the optional `configuration` parameter. Please ensure that the `metadata` object is correctly filled as it is used to configure the user experience and detect fraud. Additionally, if you pass an object to the optional `prefilledPhoneNumber`, you can set up a 2FA/MFA flow or one where the user will need to verify a specific number; this interacts `prefilledPhoneNumber.userCanEdit` to allow them to change the number to be verified.","operationId":"createSession","parameters":[{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreationDTO"}}}},"responses":{"200":{"description":"Phone verification was created successfully and ready to start.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreationResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Start a verification session","tags":["1. SDK Integration"]}},"/sdk-api/phone-verification/verification-result/v1.0.0":{"get":{"description":"Obtain the results of a verification using a session UUID and your API Key credentials. This endpoint should never be called from client-side software to avoid leaking your API Key.","operationId":"getVerificationResult","parameters":[{"name":"sessionUuid","required":true,"in":"query","schema":{"type":"string"}},{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResultResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Get verification result (v1.0.0)","tags":["1. SDK Integration"]}},"/sdk-api/phone-verification/verification-result/v1.1.0":{"get":{"description":"Obtain the results of a verification using a session UUID and your API Key credentials. This endpoint should never be called from client-side software to avoid leaking your API Key. Version 1.1.0 also includes data enrichment objects that contain information on the phone number that was verified and the context of the verification process. These data points are optional and can be ommitted to reduce latency.","operationId":"getEnrichedVerificationResult","parameters":[{"name":"sessionUuid","required":true,"in":"query","schema":{"type":"string"}},{"name":"enrichmentType","required":true,"in":"query","description":"Determines the type of enrichment you want to obtain. Take into consideration that if you request all of the data points, the payload will increase in size substantially and latency might be introduced. We recommend only getting the data points you need based on the context around the verification. By default, no enrichment is done. See [catalog of possible values here](/docs/catalogs#verification-data-enrichment-flags).","schema":{"default":0,"type":"number"}},{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichedVerificationResultResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Get verification result (v1.1.0)","tags":["1. SDK Integration"]}},"/sdk-api/phone-verification/country-codes/v1.0.0":{"get":{"description":"Obtain the full list of country codes including ISO 3166-2 codes.","operationId":"getAllCountryCodes","parameters":[{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request that returns the list of country codes.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CountryCodeResponse"}}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Get phone country codes","tags":["2. Helper Services"]}},"/standalone/send-otp/v1.0.0":{"post":{"description":"This endpoint is a standalone service that allows your application to send OTP messages via SMS, WhatsApp (requires initial setup; contact us for more information), and phone call without using the Veriph.One SDK. Please note that this service has an independent billing scheme (per message sent not successful verification), and by using it you are losing SMS pumping protection and other important security features.","operationId":"sendOTP","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendOTPPayload"}}}},"responses":{"200":{"description":"OTP message was successfully triggered; the SMS/WhatsApp messages was sent or the automated phone call was made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundMessageResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Your application needs to be setup before using the features you requested; please contact us to assist you.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Send a non-SDK OTP","tags":["2. Helper Services"]}},"/standalone/digital-footprint-search/v1.0.0":{"post":{"description":"Search for a phone number's and/or email address's presence in social media, popular mobile apps, and over 100 platforms. This process can help detect fraudsters and identity theft events. The service operates under two modes:\n- Quick search: returns a record-based payload from a limited number of sites (+30); data uses inference in some cases, so it can be outdated or imprecise.\n- Deep search: a robust process that leverage several real-time inquiry methods to obtain up-to-date and precise data on accounts; this type can take minutes to complete.\nPlease note that this service operates under an independent billing scheme, and each search type has a distinct price. Although your app can send either a phone number or an email address, we recommend sending both for better results. Finally, this service is only available to paid plans and accounts with a minimum balance of 1 USD.","operationId":"searchDigitalFootprint","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigitalFootprintSearchRequest"}}}},"responses":{"200":{"description":"Search data was successfully retrieved; the body of the response includes the payload with the information found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigitalFootprintResult"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"423":{"description":"Your application is not configured to access this service and requires approval. Contact support@veriph.one for assistance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Digital footprint search","tags":["4. Insights"]}},"/insights/phone/v1.2.1":{"post":{"description":"This endpoint is our most complete phone insights service that allows your application to get critical data on a phone number. It can be used to better understand user profiles, feed risk and credit models, stop fraud, detect hackers, and more. Please note that this service has an independent billing scheme. Finally, this service is only available to paid plans and accounts with a minimum balance of 1 USD.","operationId":"phoneInsights","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneInsightsRequest"}}}},"responses":{"200":{"description":"Insights data was successfully retrieved; the body of the response includes the payload with known information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VeriphOnePhoneInsightsResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"423":{"description":"Your application is requesting access to a data package that requires additional configuration or approval. Contact support@veriph.one for assistance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Phone number insights","tags":["4. Insights"]}},"/insights/email/v1.0.0":{"post":{"description":"This service analyzes an email address to generate relevant data points on the risk of interacting with it; ranging from detecting disposable accounts, flagging fraudlent and malicious addresses, and obtaining behavioral information.\nPlease note that this service has an independent billing scheme and each search type has a different pricing. Finally, this service is only available to paid plans and accounts with a minimum balance of 1 USD.","operationId":"emailInsights","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailInsightsRequest"}}}},"responses":{"200":{"description":"Successful request, the results of the analysis and its insights are available in the response's body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VeriphOneEmailEnrichmentResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Email analysis and insights","tags":["4. Insights"]}},"/insights/ip/v1.0.0":{"post":{"description":"This service analyzes an IP address and web interaction metadata (user agent, language headers) to generate relevant data points on the risk of interacting with it; ranging from anonymous connections, flagging fraudlent and malicious addresses, and obtaining behavioral information. The process also returns information about the IP address's geolocation and performs reverse geocoding.\nPlease note that this service has an independent billing scheme and each search type has a different pricing. Finally, this service is only available to paid plans and accounts with a minimum balance of 1 USD.","operationId":"ipAddressInsights","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpAddressInsightsRequest"}}}},"responses":{"200":{"description":"Successful request, the results of the analysis and its insights are available in the response's body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VeriphOneIpInsightsResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"IP address analysis and insights","tags":["4. Insights"]}},"/insights/geolocation/v1.0.0":{"post":{"description":"This endpoint provides comprehensive geolocation information including reverse geocoding, area statistics and nearby infrastructure analysis. It returns address details (with accuracy-based masking), security statistics, quality of life indicators, and financial infrastructure information for a given latitude and longitude. The accuracy radius parameter controls the precision of the returned address information. Even though the reverse geocoding service is available globally, statistics and risk location analysis are only available for locations within Mexico. The service also requires a paid plan.","operationId":"analyzeGeolocation","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeolocationInsightsRequest"}}}},"responses":{"200":{"description":"Geolocation data was successfully retrieved with address and statistical information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VeriphOneGeolocationInsights"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Geolocation insights and area analysis","tags":["4. Insights"]}},"/identity/validation/proof-of-address/v1.0.0":{"post":{"description":"Send a PDF or JPG file of a proof-of-address document to extract its contents using Optical Character Recognition (OCR), and, if the type of document is supported, validate its authenticity (attestation) against the company or institution that creates that type of document. Supported types:\n\n- Mexico: OCR (Comisión Federal de Electricidad / CFE, Telmex, Telcel, Megacable, Sky, Izzi) & Attestation (Comisión Federal de Electricidad / CFE).\n\nPlease note, the resulting payload and billing will change depending on the the type of document provided and if attestation is supported.","operationId":"proofOfAddressValidation","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofOfAddressValidationRequest"}}}},"responses":{"200":{"description":"A successful response after processing the provided Proof of Address document; the result will include:\n\n1. The details obtained from the OCR (if the document type is supported and valid).\n2. The results of the attestation against the entity or authority that generates this type of document.\n\n3. A score measuring the similarity of the received document and the emitting authority's records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofOfAddressValidationResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"An error related to the provide file or its contents. For example:\n1. The file is empty or not a valid base64 string. Error code 70012.\n2. The file is corrupted or unreadable. Error code 70015.\n3. The document type is unsupported or invalid. Error code 70011.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Proof of address validation (OCR + Attestation)","tags":["3. Identity Validation"]}},"/identity/validation/proof-of-address/ocr/v1.0.0":{"post":{"description":"Note: This service, along with the attestation service, is a split form of the overall Proof of Address validation service; we recommend using that one, unless your use case requires the separation of OCR and attestation processes.\n\nSend a PDF or JPG file of a proof-of-address document to extract its contents using Optical Character Recognition (OCR). Supported types:\n\n- Mexico: OCR (Comisión Federal de Electricidad / CFE, Telmex, Telcel, Megacable, Sky, Izzi).\n\nPlease note, the resulting payload and billing will change depending on the the type of document provided.","operationId":"proofOfAddressOcr","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdempotentProofOfAddressOcrRequest"}}}},"responses":{"200":{"description":"A successful response after processing the provided Proof of Address document; the result will include the details obtained from the OCR (if the document type is supported and valid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofOfAddressOcrResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"An error related to the provide file or its contents. For example:\n1. The file is empty or not a valid base64 string. Error code 70012.\n2. The file is corrupted or unreadable. Error code 70015.\n3. The document type is unsupported or invalid. Error code 70011.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Proof of address OCR","tags":["3. Identity Validation"]}},"/identity/validation/proof-of-address/attestation/v1.0.0":{"post":{"description":"Note: This service, along with the OCR service, is a split form of the overall Proof of Address validation service; we recommend using that one, unless your use case requires the separation of OCR and attestation processes.\n\nTrigger the attestation process of a proof-of-address document previously sent to our OCR processing service to validate its authenticity (attestation) against the company or institution that creates that type of document. Supported types:\n\n- Mexico: Attestation (Comisión Federal de Electricidad / CFE).\n\nPlease note, the resulting payload and billing will change depending on the the type of document provided and if attestation is supported.","operationId":"proofOfAddressAttestation","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofOfAddressAttestationRequest"}}}},"responses":{"200":{"description":"A successful response after processing the provided Proof of Address document; the response will include the results of the attestation against the entity or authority that generates this type of document and a score measuring the similarity of the received document and the emitting authority's records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofOfAddressAttestationResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"412":{"description":"An error related to a failed precondition such as a non-existent OCR extraction process for the provided request UUID, an invalid request UUID or an unsupported document type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Proof of address attestation","tags":["3. Identity Validation"]}},"/identity/validation/tax-id/v1.0.0":{"post":{"description":"An endpoint that validates a person's tax ID or national ID in the country's governmental official database. Supported types:\n\n- Mexico: RFC or CURP (When using CURP, the tax ID number will be built from scratch and might lead to a lower accuracy).\n\nPlease note, the resulting payload and billing will change depending on the the type of ID provided.","operationId":"taxIdValidation","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxIdValidationRequest"}}}},"responses":{"200":{"description":"A successful response after processing the provided tax ID; the response will include the results of the validation against the country's tax authority.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxIdValidationResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Tax ID validation","tags":["3. Identity Validation"]}},"/identity/validation/education-history/search/v1.0.0":{"post":{"description":"A service that searches for a person's educational history (undergrad and postgrad degrees) in the country's governmental official database. Supported countries:\n\n- Mexico (your application can provide a full name (and optional date of birth) or a national ID (CURP) to perform the search).\n\nPlease note, the resulting payload and billing will change depending on the the type of data used provided for the search.","operationId":"educationHistorySearch","parameters":[{"name":"authorization","in":"header","description":"Your Veriph.One API Key Secret; using the Basic auth structure: `Basic XXXX...XXXX`","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"Your Veriph.One API Key","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EducationHistorySearchRequest"}}}},"responses":{"200":{"description":"A successful response after performing the search; the response will include the available results from the country's governmental official database.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EducationHistorySearchResponse"}}}},"400":{"description":"No API Key provided, credentials invalid, or invalid values in request contents (e.g. body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Your application is on a free plan or doesn't have sufficient balance to perform the operation. Visit https://dashboard.veriph.one to fix the issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API Key or Client status have made the credentials unusable; or there's an issue with the credentials provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Education history search","tags":["3. Identity Validation"]}},"/health-api/check":{"get":{"description":"Simple endpoint to check on our servers' availability.","operationId":"checkServiceHealth","parameters":[],"responses":{"200":{"description":"Successful request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthCheckResponse"}}}}},"summary":"Health Check","tags":["5. Misc"]}}},"info":{"title":"Veriph.One's API","description":"This is the documentation for Veriph.One's integration and service APIs. You can find more information about our company at [www.veriph.one](https://veriph.one).\n# Introduction\nThis API is grouped into specific categories based on common platform use-cases; for example:\n- The **SDK Integration** group is used to make a complete integration with our platform and use all of our verification methods insided your mobile and web apps. This is the most common use case.\n- The **Helper Services** section aggregates endpoints used for more complex interactions with our platforms where you want to go beyond our SDK's functionality.\n- The **Identity Validation** category aggregates endpoints relevant to complement identity verifications during a KYC flow.\n- The **Insights** bracket helps your company perform deep analysis of a user profile to protect against fraud and identity theft without adding friction to your user experience.\n- Lastly, the **Misc** category is used to interact and monitor our infrastructure.\n# OpenAPI Specification\nThis API is documented in **OpenAPI format** and can also be explored using Swagger via its [standalone website](https://service.veriph.one/swagger), or its [JSON](https://service.veriph.one/swagger-json) and [YAML](https://service.veriph.one/swagger-yaml) definitions.\n# Authentication\nThe endpoints shown here are offered under API-Key-based authentication. Please consider that some endpoints require only your API Key, while others need your Secret as well. Keep your credentials safe and never include them in your code repositories as plain text. Also, don't expose your API Secret to client-side code, as it can be reverse-engineered.\n# Versioning\nOur versioning strategy goes beyond a global API version, and we follow a pattern where endpoints have individual versions instead of the API as a whole. This allows for more versatility and better backwards compatibility. Please consider that only major versions (e.g., v1.X.X or v2.X.X) will be incompatible to endpoints with previous versions.\n","version":"1.X.X","contact":{}},"tags":[],"servers":[],"components":{"schemas":{"ExternalPhoneBundle":{"type":"object","properties":{"countryCode":{"type":"string","description":"Expected number's country code, without '+' sign or non-numeric characters"},"cellphoneNumber":{"type":"string","description":"Expected phone number without country code or non-numeric characters"},"userCanEdit":{"type":"boolean","description":"Defines whether the user can change the expected phone number mid-verification","default":false}},"required":["countryCode","cellphoneNumber"]},"SessionMetadata":{"type":"object","properties":{"userId":{"type":"string","description":"An ID that can be used by your application to link our verification session UUID to a unique user or transaction. Avoid sending personal o sensitive information."},"userAgent":{"type":"string","description":"Used to detect fraudsters, bots, and identity theft; please ensure that you are sending proper values as obtained by your server."},"ipAddress":{"type":"string","description":"The user's IP address captured by your server. This is a critical data point to detect fraud, offer the best verification methods available, among other operations."}},"required":["userId","ipAddress"]},"SessionConfigurationDTO":{"type":"object","properties":{"locale":{"type":"string","description":"String determining the language to be shown to the user in the UI in ISO 639-1 format.","default":"en"},"enforceInput":{"type":"boolean","default":false,"description":"Force users to manually enter their phone number before initiating Inverse OTP verification."}},"required":["locale"]},"SessionCreationDTO":{"type":"object","properties":{"prefilledPhoneNumber":{"description":"This object determines whether the verification process will capture an unknown number or do a 2FA/MFA flow with a known one. In case of the latter, the verification will be rejected if the user verifies a different number.","allOf":[{"$ref":"#/components/schemas/ExternalPhoneBundle"}]},"metadata":{"description":"Necessary data to detect bots, unique transactions, fraudsters, and user's approximate location.","allOf":[{"$ref":"#/components/schemas/SessionMetadata"}]},"configuration":{"description":"Used to setup the verification process based on context provided by your application.","allOf":[{"$ref":"#/components/schemas/SessionConfigurationDTO"}]}},"required":["metadata"]},"SessionCreationResponse":{"type":"object","properties":{"uuid":{"type":"string","description":"The verification session UUID to be used."},"createdAt":{"format":"date-time","type":"string","description":"String containing the session's creation date-time in ISO8601 format."},"redirectionUrl":{"type":"string","description":"The verification session URL to be used by web apps for redirection to the verification UI."}},"required":["uuid","createdAt","redirectionUrl"]},"ErrorResponse":{"type":"object","properties":{"internalErrorCode":{"type":"number","description":"Non-http-code that facilitates debugging. Visit the [Error Codes](/docs/catalogs#api-error-codes) page for more details."},"errorMessage":{"type":"string","description":"Developer friendly error message in english. In some cases, this message might be ommitted for security reasons."}},"required":["internalErrorCode"]},"VerificationAttemptResponse":{"type":"object","properties":{"uuid":{"type":"string","description":"The attempt's unique ID."},"countryCodeInput":{"type":"string","nullable":true,"description":"Country code of the phone number used or selected by the user."},"phoneNumberInput":{"type":"string","nullable":true,"description":"Phone number used or submitted by the user."},"method":{"type":"number","description":"Verification method used. See [catalog of possible values here](/docs/catalogs#verification-method-types)."},"status":{"type":"number","description":"Verification attempt's current state. See [catalog of possible values here](/docs/catalogs#attempt-statuses)."},"createdAt":{"format":"date-time","type":"string","description":"The attempt's creation date time in ISO8601 format."}},"required":["uuid","countryCodeInput","phoneNumberInput","method","status","createdAt"]},"VerificationResultResponse":{"type":"object","properties":{"prefilledCountryCode":{"type":"string","nullable":true,"description":"The prefilled phone number's country code when the verification session was created."},"prefilledPhoneNumber":{"type":"string","nullable":true,"description":"The prefilled phone number when the verification session was created."},"createdAt":{"format":"date-time","type":"string","description":"String containing the session's creation date-time in ISO8601 format."},"closedAt":{"format":"date-time","type":"string","description":"String containing the session's closure date-time in ISO8601 format. Null if session is still open."},"userId":{"type":"string","nullable":true,"description":"The ID passed by your application to the session creation's `metadata.userId` parameter."},"firstSuccessfulAttempt":{"nullable":true,"description":"The successful verification result object, if any.","allOf":[{"$ref":"#/components/schemas/VerificationAttemptResponse"}]},"attempts":{"description":"Array of attempts made by user.","type":"array","items":{"$ref":"#/components/schemas/VerificationAttemptResponse"}}},"required":["prefilledCountryCode","prefilledPhoneNumber","createdAt","closedAt","userId","firstSuccessfulAttempt","attempts"]},"CountryCodeBundle":{"type":"object","properties":{"countryIsoCode3166_2":{"type":"string","description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."},"phoneCode":{"type":"string","description":"Phone code for this country; to be used as a preffix on a phone number."}},"required":["countryIsoCode3166_2","phoneCode"]},"InitialSessionConfiguration":{"type":"object","properties":{"prefilledCountryCode":{"nullable":true,"description":"The prefilled phone number's country code when the verification session was created. Including the country's ISO3166-2 code","allOf":[{"$ref":"#/components/schemas/CountryCodeBundle"}]},"prefilledPhoneNumber":{"type":"string","nullable":true,"description":"The prefilled phone number when the verification session was created."},"userId":{"type":"string","nullable":true,"description":"The ID passed by your application to the session creation's `metadata.userId` parameter."},"locale":{"type":"string","nullable":true,"description":"String in ISO 639-1 format sent when creating this session to determine the language first shown to the user in the UI."},"enforceInput":{"type":"boolean","nullable":true,"description":"Setting sent when creating this session to force users to manually enter their phone number before initiating Inverse OTP verification."}},"required":["prefilledCountryCode","prefilledPhoneNumber","userId","locale","enforceInput"]},"VerificationStatusPayload":{"type":"object","properties":{"isOpen":{"type":"boolean","description":"Determines if the verification session is currently open."},"wasSuccessful":{"type":"boolean","description":"Determines if the verification session was successful."},"hasErrors":{"type":"boolean","description":"Determines if the verification session failed or encountered issues."},"errorDestinationMismatch":{"type":"boolean","description":"Flag raised when, using the Inverse OTP method, the user tried to tamper with the result."},"errorOriginMismatch":{"type":"boolean","description":"Flag raised when, using the Inverse OTP method, the user sent the message from a different number that expected (i.e., when prefilling one)."},"errorInvalidated":{"type":"boolean","description":"Flag raised when the attempt status was invalided because the session closed."},"errorExpired":{"type":"boolean","description":"Flag marking an expired attempt; meaning the user didn't submit an OTP within the expected time window."},"errorClientDisabled":{"type":"boolean","description":"Flag raised when a client application was disabled due to pending payment or administrative reasons."},"errorMethodTampering":{"type":"boolean","description":"Flag raised when the attempt was invalided because potential tampering due to mismatching verification methods was detected."},"errorTooManySubmissions":{"type":"boolean","description":"Flag raised when the user submits too many OTPs; possibly trying to guess it."},"errorExceededAttemptQuota":{"type":"boolean","description":"Flag raised when the attempt was invalided because the user exceeded the number of retries."},"errorUserCancelledAttempt":{"type":"boolean","description":"Flag raised when the attempt was made invalid by a user-triggered cancellation/request."}},"required":["isOpen","wasSuccessful","hasErrors","errorDestinationMismatch","errorOriginMismatch","errorInvalidated","errorExpired","errorClientDisabled","errorMethodTampering","errorTooManySubmissions","errorExceededAttemptQuota","errorUserCancelledAttempt"]},"ServiceProviderInfo":{"type":"object","properties":{"legalName":{"type":"string","description":"Legal name of the service provider."},"brandName":{"type":"string","nullable":true,"description":"Brand or public name of the service provider."},"isRetail":{"type":"boolean","nullable":true,"description":"True if the service provider serves end-consumers. Null if unknown."},"isB2B":{"type":"boolean","nullable":true,"description":"True if the service provider serves companies. Null if unknown."},"sellsVirtualNumbers":{"type":"boolean","nullable":true,"description":"True if the service provider sells virtual numbers. Null if unknown."},"sellsSatellitePhones":{"type":"boolean","nullable":true,"description":"True if the service provider sells satellite telephony. Null if unknown."},"isWhiteLabel":{"type":"boolean","nullable":true,"description":"True if the service provider sells white-label telephony or is B2B2C. Null if unknown."},"sellsIPTelephony":{"type":"boolean","nullable":true,"description":"True if the service provider sells IP Telephony. Null if unknown."},"sellsVoIP":{"type":"boolean","nullable":true,"description":"True if the service provider sells VoIP services. Null if unknown."},"sellsVoLTE":{"type":"boolean","nullable":true,"description":"True if the service provider sells VoLTE services. Null if unknown."}},"required":["legalName","brandName","isRetail","isB2B","sellsVirtualNumbers","sellsSatellitePhones","isWhiteLabel","sellsIPTelephony","sellsVoIP","sellsVoLTE"]},"GeographicNumberInfo":{"type":"object","properties":{"locality":{"type":"string","description":"Locality where the phone number was registered."},"municipality":{"type":"string","description":"Municipality where the phone number was registered."},"state":{"type":"string","description":"State or equivalent where the phone number was registered."},"type":{"type":"number","nullable":true,"description":"Type of phone number. Possible values: Mobile Caller-Party-Pays [1000], Mobile Receiver-Party-Pays [2000], Landline [3000], Unknown [null]."}},"required":["locality","municipality","state","type"]},"NonGeographicNumberInfo":{"type":"object","properties":{"type":{"type":"number","nullable":true,"description":"Phone number type. Possible values: Satellite [10000], SharedCharges [20000], PersonalWithCallTransfer [30000], ReverseCharges [40000], Surcharges [50000], Unknown [null]."}},"required":["type"]},"NumberMetadata":{"type":"object","properties":{"isGeographic":{"type":"boolean","description":"False if the number is a type of phone not registered or linked to a specific geography. Nearly all consumer numbers are geographical."},"geographicData":{"nullable":true,"description":"Details of the phone number if it is geographical; null otherwise.","allOf":[{"$ref":"#/components/schemas/GeographicNumberInfo"}]},"nonGeographicData":{"nullable":true,"description":"Details of the phone number if it is non-geographical; null otherwise.","allOf":[{"$ref":"#/components/schemas/NonGeographicNumberInfo"}]}},"required":["isGeographic","geographicData","nonGeographicData"]},"BlacklistItem":{"type":"object","properties":{"firstAppearance":{"format":"date-time","type":"string","description":"First date-time (ISO8601) the phone number appeared on this blacklist."},"lastReport":{"format":"date-time","type":"string","description":"Last date-time (ISO8601) the phone number appeared on this blacklist."},"listName":{"type":"string","description":"Name of the list where the phone was found."}},"required":["firstAppearance","lastReport","listName"]},"BlacklistMatches":{"type":"object","properties":{"publicVirtualNumbers":{"description":"Matches of the phone number against blacklists of public virtual numbers used by fraudsters and bots.","type":"array","items":{"$ref":"#/components/schemas/BlacklistItem"}},"scammerBlacklists":{"description":"Matches of the phone number against blacklists of known scammer's numbers.","type":"array","items":{"$ref":"#/components/schemas/BlacklistItem"}},"communityFraudBlacklists":{"description":"Matches of the phone number against blacklists built by the Veriph.One community's reports of fraud.","type":"array","items":{"$ref":"#/components/schemas/BlacklistItem"}}},"required":["publicVirtualNumbers","scammerBlacklists","communityFraudBlacklists"]},"KnownCapabilities":{"type":"object","properties":{"lastSMSReceived":{"format":"date-time","type":"string","nullable":true,"description":"Last known date-time (ISO8601) an SMS was received by or sent to this phone number. It can be a Veriph.One OTP or a report from a data partner."},"lastSMSSent":{"format":"date-time","type":"string","nullable":true,"description":"Last known date-time (ISO8601) an SMS was sent by this phone number. It can be a Veriph.One OTP or a report from a data partner."},"lastWhatsAppReceived":{"format":"date-time","type":"string","nullable":true,"description":"Last known date-time (ISO8601) a WhatsApp message was received by or sent to this phone number. It can be a Veriph.One OTP or a report from a data partner."},"lastWhatsAppSent":{"format":"date-time","type":"string","nullable":true,"description":"Last known date-time (ISO8601) a WhatsApp message was sent by this phone number. It can be a Veriph.One OTP or a report from a data partner."},"lastPhoneCallReceived":{"format":"date-time","type":"string","nullable":true,"description":"Last known date-time (ISO8601) a phone call was received by or made to this phone number. It can be a Veriph.One OTP or a report from a data partner."},"lastPhoneCallMade":{"format":"date-time","type":"string","nullable":true,"description":"Last known date-time (ISO8601) a phone call was made by this phone number. It can be a Veriph.One OTP or a report from a data partner."}},"required":["lastSMSReceived","lastSMSSent","lastWhatsAppReceived","lastWhatsAppSent","lastPhoneCallReceived","lastPhoneCallMade"]},"EnrichmentPayload":{"type":"object","properties":{"serviceProvider":{"nullable":true,"description":"Known information on the service provider linked to this phone number. Null if the information is unavailable. Currently only available for Mexico, more countries coming soon.","allOf":[{"$ref":"#/components/schemas/ServiceProviderInfo"}]},"numberMetadata":{"nullable":true,"description":"Known information on the phone number. Null if the information is unavailable. Currently only available for Mexico, more countries coming soon.","allOf":[{"$ref":"#/components/schemas/NumberMetadata"}]},"blacklistMatches":{"nullable":true,"description":"Element in Early-Access, only available to applications that have opted-in to this service. Used to determine if the phone number is found on fraudster, scammer and public virtual number blacklists.","allOf":[{"$ref":"#/components/schemas/BlacklistMatches"}]},"knownCapabilities":{"description":"Points of the interaction of this phone number with the Veriph.One platform or its data partners that show its current or past capabilities.","allOf":[{"$ref":"#/components/schemas/KnownCapabilities"}]}},"required":["serviceProvider","numberMetadata","blacklistMatches","knownCapabilities"]},"NumberPayload":{"type":"object","properties":{"countryCode":{"description":"Country code of the phone number used or selected by the user.","allOf":[{"$ref":"#/components/schemas/CountryCodeBundle"}]},"phoneNumber":{"type":"string","description":"Phone number used or submitted by the user."},"metadata":{"nullable":true,"description":"This phone number's enrichment metadata. Returned `null` for non-successful attempts or when not requested.","allOf":[{"$ref":"#/components/schemas/EnrichmentPayload"}]}},"required":["countryCode","phoneNumber","metadata"]},"EnrichedVerificationResult":{"type":"object","properties":{"status":{"type":"number","nullable":true,"description":"Final attempt (if any) current raw state. See [catalog of possible values here](/docs/catalogs#attempt-statuses)."},"parsedStatus":{"nullable":true,"description":"A transformation of the raw `status` field into boolean flags indicating the final attempt's (if any) current state.","allOf":[{"$ref":"#/components/schemas/VerificationStatusPayload"}]},"methodUsedSuccessfully":{"type":"number","nullable":true,"description":"Verification method used by the successful attempt (if any) in this session. See [catalog of possible values here](/docs/catalogs#verification-method-types)."},"verifiedNumber":{"nullable":true,"description":"Phone number successfully verified during this verification session, including enrichment data (if applicable).","allOf":[{"$ref":"#/components/schemas/NumberPayload"}]}},"required":["status","parsedStatus","methodUsedSuccessfully","verifiedNumber"]},"City":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in different locales."},"confidence":{"type":"number","nullable":true,"description":"A value from 0-100 signaling the confidence that the city is correct."}},"required":["geoNameId","localizedName","confidence"]},"Continent":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in different locales."},"code":{"type":"string","description":"2-letter code for the continent the connection is coming from. Possible values: AF (Africa), AN (Antartica), AS (Asia), EU (Europe), NA (North America), OC (Oceania), SA (South America)"}},"required":["geoNameId","localizedName","code"]},"Country":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in different locales."},"confidence":{"type":"number","nullable":true,"description":"A value from 0-100 signaling the confidence that the city is correct."},"isoCode":{"type":"string","description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."}},"required":["geoNameId","localizedName","confidence","isoCode"]},"Geolocation":{"type":"object","properties":{"city":{"nullable":true,"description":"The city the connection is coming from.","allOf":[{"$ref":"#/components/schemas/City"}]},"continent":{"nullable":true,"description":"The continent the connection is coming from.","allOf":[{"$ref":"#/components/schemas/Continent"}]},"country":{"nullable":true,"description":"The country the connection is coming from.","allOf":[{"$ref":"#/components/schemas/Country"}]},"accuracyRadiusInKm":{"type":"number","nullable":true,"description":"The accuracy radius in kilometer for the Lat/Lng coordinates of the interpreted geolocation."},"avgIncomeInUSD":{"type":"number","nullable":true,"description":"The known average income in USD of the region the connection is coming from. This value has limited availability."},"latitude":{"type":"number","nullable":true,"description":"The interpreted geolocation's latitude."},"longitude":{"type":"number","nullable":true,"description":"The interpreted geolocation's longitude"},"populationDensity":{"type":"number","nullable":true,"description":"The estimated number of people per square kilometer. This field has limited availability."},"timezone":{"type":"string","nullable":true,"description":"IANA Time Zone for the interpreted geolocation."},"zipCode":{"type":"string","nullable":true,"description":"The approximated zip code of the interpreted geolocation. This value might not be available or complete on all countries."},"zipCodeConfidence":{"type":"number","nullable":true,"description":"A value from 0-100 indicating the confidence that the postal code is correct."}},"required":["city","continent","country","accuracyRadiusInKm","avgIncomeInUSD","latitude","longitude","populationDensity","timezone","zipCode","zipCodeConfidence"]},"CountryAssociation":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in different locales."},"confidence":{"type":"number","nullable":true,"description":"A value from 0-100 signaling the confidence that the city is correct."},"isoCode":{"type":"string","description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."},"type":{"type":"string","description":"A string indicating the type of entity that is representing the country. Possible values: 'military'."}},"required":["geoNameId","localizedName","confidence","isoCode","type"]},"IpMetadata":{"type":"object","properties":{"geolocation":{"description":"The interpreted geolocation of the connect as obtained from the IP address.","allOf":[{"$ref":"#/components/schemas/Geolocation"}]},"ipCountryRegistration":{"nullable":true,"description":"The country where the IP address' block was registered by it's ISP. May be different from the user's country.","allOf":[{"$ref":"#/components/schemas/Country"}]},"ipCountryAssociation":{"nullable":true,"description":"Used to identify an IP address' linked to another country than where they are geographically located. For instance: IP addresses belonging to embassies or military bases.","allOf":[{"$ref":"#/components/schemas/CountryAssociation"}]},"ipCountrySubdivisions":{"description":"An ordered list (descending) of, typically, the state, province, borough, or similar subdivisions of the country where request is coming from. The structure and number of divisions may vary by country.","type":"array","items":{"$ref":"#/components/schemas/Country"}},"autonomousSystemNumber":{"type":"number","nullable":true,"description":"The Autonomous System Number associated to this IP address, if any. More info on [ASNs here](https://www.cloudflare.com/learning/network-layer/what-is-an-autonomous-system/)"},"autonomousSystemOrganization":{"type":"string","nullable":true,"description":"The organization linked to the Autonomous System associated to this IP address, if any. More info on [this here](https://www.cloudflare.com/learning/network-layer/what-is-an-autonomous-system/)"},"connectionType":{"type":"string","nullable":true,"description":"The connection type used by this IP Address; possible values: Cable/DSL, Cellular, Corporate, Dialup, Satellite."},"domain":{"type":"string","nullable":true,"description":"The domain (e.g., example.com) linked to this IP Address, if any."},"externalIpAddress":{"type":"string","nullable":true,"description":"In case the IP address is behind a NAT, the external and reachable IP address. Otherwise, the same IP may be returned."},"isAnonymous":{"type":"boolean","description":"True if the IP belongs to an anonymous network."},"isAnonymousVpn":{"type":"boolean","description":"True if the IP is registered by an anonymous VPN vendor."},"isHostingProvider":{"type":"boolean","description":"True if the IP is linked to a hosting or VPN provider."},"isPublicProxy":{"type":"boolean","description":"True if the address is a public proxy."},"isResidentialProxy":{"type":"boolean","description":"True if the IP belongs to a residential ISP and operated on a suspected anonymizing network."},"isTorExitNode":{"type":"boolean","description":"True when the address is a Tor exit node."},"ispName":{"type":"string","nullable":true,"description":"The name of the ISP linked to the IP address."},"mobileCountryCode":{"type":"string","nullable":true,"description":"The mobile country code (MCC) linked to the IP address & ISP. More [info here](https://en.wikipedia.org/wiki/Mobile_country_code)"},"mobileNetworkCode":{"type":"string","nullable":true,"description":"The mobile network code (MNC) linked to the IP address & ISP. More [info here](https://en.wikipedia.org/wiki/Mobile_country_code)"},"network":{"type":"string","nullable":true,"description":"The network associated to the IP address."},"organization":{"type":"string","nullable":true,"description":"The organization linked to the IP Address, if known."},"staticIpScore":{"type":"number","nullable":true,"description":"A number ranging from 0 to 99.99 indicating how static or dynamic the IP address is. The higher, the more likely it is static. Usually, cellular connections score below 1, while Cable/DSL above 30."},"userCountInLast24Hrs":{"type":"number","nullable":true,"description":"The number of estimated users that have shared this IP address in the past 24 hrs. For IPv6, the count is for /64 networks."},"userType":{"type":"string","nullable":true,"description":"The interpreted type of IP address. Potential values: business, cafe, cellular, college, consumer_privacy_network, content_delivery_network, dialup, government, hosting, library, military, residential, router, school, search_engine_spider, traveler."}},"required":["geolocation","ipCountryRegistration","ipCountryAssociation","ipCountrySubdivisions","autonomousSystemNumber","autonomousSystemOrganization","connectionType","domain","externalIpAddress","isAnonymous","isAnonymousVpn","isHostingProvider","isPublicProxy","isResidentialProxy","isTorExitNode","ispName","mobileCountryCode","mobileNetworkCode","network","organization","staticIpScore","userCountInLast24Hrs","userType"]},"ExchangedMessage":{"type":"object","properties":{"sentAt":{"format":"date-time","type":"string","nullable":true},"receivedAt":{"format":"date-time","type":"string","nullable":true},"channel":{"type":"number","description":"The channel used for the message. Potential values: SMS [0], WhatsApp [1], Phone Call [2]."},"wasOTP":{"type":"boolean","description":"True if the message was an OTP or matched that structure."},"userWhatsAppProfileName":{"type":"string","nullable":true,"description":"The user's WhatsApp display name, if available."},"usedThirdPartyIntegration":{"type":"boolean","description":"True if the message was obtained from a third-party integration linked to your account."}},"required":["sentAt","receivedAt","channel","wasOTP","userWhatsAppProfileName","usedThirdPartyIntegration"]},"EnrichedVerificationAttemptResponse":{"type":"object","properties":{"uuid":{"type":"string","description":"The attempt's unique ID."},"method":{"type":"number","description":"The verification method assigned to this attempt. See [catalog of possible values here](/docs/catalogs#verification-method-types)."},"status":{"type":"number","description":"Verification attempt's current state in raw form. See [catalog of possible values here](/docs/catalogs#attempt-statuses)."},"createdAt":{"format":"date-time","type":"string","description":"The attempt's creation date time in ISO8601 format."},"attemptCancellationReason":{"type":"string","nullable":true,"description":"The user's cancellation reason for this attempt, if any."},"numberUsed":{"nullable":true,"description":"The phone number related to this attempt.","allOf":[{"$ref":"#/components/schemas/NumberPayload"}]},"messagesReceivedFromUser":{"description":"The messages sent by the user linked to this attempt.","type":"array","items":{"$ref":"#/components/schemas/ExchangedMessage"}},"messagesSentToUser":{"description":"The messages sent to the user linked to this attempt.","type":"array","items":{"$ref":"#/components/schemas/ExchangedMessage"}}},"required":["uuid","method","status","createdAt","attemptCancellationReason","numberUsed","messagesReceivedFromUser","messagesSentToUser"]},"VerificationMetadata":{"type":"object","properties":{"userAgent":{"type":"string","nullable":true,"description":"The User Agent as reported by your application when creating the session."},"userIpAddress":{"type":"string","nullable":true,"description":"The user's IP address as reported by your application, without a proxy, if originally included."},"proxyIpAddress":{"type":"string","nullable":true,"description":"The proxy address extracted from the IP address reported by your application, in case it was included."},"userIpMetadata":{"nullable":true,"description":"The IP address metadata payload, including ISP and geolocation data points. This object will be omitted unless requested.","allOf":[{"$ref":"#/components/schemas/IpMetadata"}]},"sessionDuration":{"type":"number","nullable":true,"description":"The duration of the verification session in miliseconds. Null if the session is still open."},"attempts":{"description":"The list of attempts linked to this verification session.","type":"array","items":{"$ref":"#/components/schemas/EnrichedVerificationAttemptResponse"}},"languagesUsed":{"description":"The languages used by the user/device during this verification session. This field is in Alpha, might return an incomplete list.","type":"array","items":{"type":"string"}}},"required":["userAgent","userIpAddress","proxyIpAddress","userIpMetadata","sessionDuration","attempts","languagesUsed"]},"EnrichedVerificationResultResponse":{"type":"object","properties":{"uuid":{"type":"string","description":"The verification session's UUID."},"createdAt":{"format":"date-time","type":"string","description":"The verification session's creation date time in ISO8601 format."},"closedAt":{"format":"date-time","type":"string","nullable":true,"description":"String containing the session's closure date-time in ISO8601 format. Null if session is still open."},"initialConfiguration":{"description":"The configuration originally sent by your application when creating the verification session.","allOf":[{"$ref":"#/components/schemas/InitialSessionConfiguration"}]},"type":{"type":"string","description":"The platform type for this verification, based on the API Key setup. Possible values: Web, Android, iOS, Mobile."},"result":{"description":"An object containing the result of the verification.","allOf":[{"$ref":"#/components/schemas/EnrichedVerificationResult"}]},"verificationMetadata":{"description":"An object containing data points related to the verification context, including geolocation obtained from the IP address and other metadata.","allOf":[{"$ref":"#/components/schemas/VerificationMetadata"}]}},"required":["uuid","createdAt","closedAt","initialConfiguration","type","result","verificationMetadata"]},"CountryCodeResponse":{"type":"object","properties":{"uuid":{"type":"string","description":"UUID generated by Veriph.One for this Country Code."},"phoneCode":{"type":"string","description":"Phone code for this country; to be used as a preffix on a phone number."},"iso3166Code":{"type":"string","description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."}},"required":["uuid","phoneCode","iso3166Code"]},"SendOTPPayload":{"type":"object","properties":{"countryCode":{"type":"string","description":"Expected number's country code, without '+' sign or non-numeric characters"},"cellphoneNumber":{"type":"string","description":"Expected phone number without country code or non-numeric characters"},"channel":{"type":"number","description":"The channel to use for the message. Values: SMS [0], WhatsApp [1], Phone Call [2]."},"otpCode":{"type":"string","description":"The OTP to include in the message template. Enforced string length range: 4-16. Only alphanumeric characters accepted (no diacritics, whitespace or symbols): 0-9, a-z, and A-Z."},"brandLabel":{"type":"string","description":"A string ignored for WhatsApp but used for other channels with the purpose of letting the user know who is sending the OTP. Use a short brand/product name, at least 2 characters long. The string might be shortened if space is needed to fit the message inside a single SMS message. The string is shown inside parentheses for SMS; for example, in english: `({brandLabel}) Your verification code is ${otpCode}. Do not share it with others`. For phone calls, the structure is as follows: `Your verification code for ${brandLabel} is ${otpCode}. Do not share it with others.`."},"locale":{"type":"string","description":"String determining the language of the message to be sent in ISO 639-1 format. Currently, only `en` and `es` are supported.","default":"en"},"userAgent":{"type":"string","description":"Used to detect fraudsters, bots, and identity theft; please ensure that you are sending proper values as obtained by your server.","nullable":true},"ipAddress":{"type":"string","description":"The user's IP address captured by your server. This is a critical data point to detect fraud, offer the best verification methods available, among other operations.","nullable":true}},"required":["countryCode","cellphoneNumber","channel","otpCode","brandLabel","locale","userAgent","ipAddress"]},"OutboundMessageResponse":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"An ISO8601 date-time string indicating the time the message was sent."},"countryCode":{"type":"string","description":"Expected number's country code, without '+' sign or non-numeric characters"},"phoneNumber":{"type":"string","description":"Expected phone number without country code or non-numeric characters"},"channel":{"type":"number","description":"The channel to use for the message. Values: SMS [0], WhatsApp [1], Phone Call [2]."},"locale":{"type":"string","description":"String determining the language of the message to be sent in ISO 639-1 format. Currently, only `en` and `es` are supported."},"referenceId":{"type":"string","description":"String containing an optional reference ID provided by some telco","nullable":true}},"required":["createdAt","countryCode","phoneNumber","channel","locale","referenceId"]},"SplitPhoneBundle":{"type":"object","properties":{"countryCode":{"type":"string","nullable":false,"description":"Number's country code, without '+' sign or non-numeric characters"},"phoneNumber":{"type":"string","nullable":false,"description":"Phone number without country code or non-numeric characters"}},"required":["countryCode","phoneNumber"]},"PolymorphicInputPhone":{"type":"object","properties":{"ituFormatedPhoneNumber":{"type":"string","nullable":true,"description":"The phone number to enrich; must be a string in E.164 format (e.g., +14155552671). Can only be null if splitPhoneNumber is provided. This field is mutually exclusive with splitPhoneNumber and will be ignored if the other is sent."},"splitPhoneNumber":{"nullable":true,"description":"The phone number to enrich provided as an object that separates Country Code and Phone Number. Can only be null if ituFormatedPhoneNumber is provided. This field is mutually exclusive with ituFormatedPhoneNumber and is preferred over it as it has faster response times.","allOf":[{"$ref":"#/components/schemas/SplitPhoneBundle"}]}},"required":["ituFormatedPhoneNumber","splitPhoneNumber"]},"DigitalFootprintSearchRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"phoneNumber":{"nullable":true,"description":"The phone number to use for the search. It can be provided as a string in E.164 format (e.g., +14155552671) or an object containing the country code and number separately. Can only be null if an email is provided.","allOf":[{"$ref":"#/components/schemas/PolymorphicInputPhone"}]},"email":{"type":"string","nullable":true,"description":"The email address to use for the search. Must be a valid email address; if the email is invalid, the service will treat it as null. Can only be null if phoneNumber is provided."},"searchTypes":{"type":"array","nullable":false,"description":"The desired search method to be used in the form of a string array, please consider that this is directly linked to pricing and using quick search will return some fields as null. Morever, including a search method might increase the cost of your request and make it slower (as more data is queried and generated). Contact your sales representative for more details.","items":{"type":"string","enum":["quick","deep"]}}},"required":["phoneNumber","email","searchTypes"]},"DigitalFootprintCategoryStats":{"type":"object","properties":{"adult":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"blogging":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"business":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"creative":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"crypto":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"dating":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"delivery":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"design":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"ecommerce":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"education":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"emailService":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"employment":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"entertainment":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"events":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"finance":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"freelancing":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"gambling":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"gigEconomy":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"messaging":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"news":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"socialMedia":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"softwareEngineering":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"sports":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"streaming":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"technology":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"travel":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"utilities":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."},"workTools":{"type":"number","nullable":false,"description":"The number of associated services linked to this category."}},"required":["adult","blogging","business","creative","crypto","dating","delivery","design","ecommerce","education","emailService","employment","entertainment","events","finance","freelancing","gambling","gigEconomy","messaging","news","socialMedia","softwareEngineering","sports","streaming","technology","travel","utilities","workTools"]},"IdentityFactorFootprintStats":{"type":"object","properties":{"totalAssociatedServices":{"type":"number","nullable":false,"description":"The total number of associated services linked to this identity factor. In other words, the number of sites or platforms this identity factor has an account on."},"associatedServicesByCategory":{"nullable":false,"description":"An object containing the number of associated services linked to this identity factor grouped by category.","allOf":[{"$ref":"#/components/schemas/DigitalFootprintCategoryStats"}]},"servicesWithoutAssociation":{"type":"number","nullable":false,"description":"The number of sites and platforms where this identity factor was searched but not found; meaning there's high likelihood the user does not have an account on those platforms."},"riskLevel":{"type":"string","enum":["low","medium","high","very_high"],"nullable":false,"description":"The risk level associated with this identity factor based entirely on their digital footprint and online presence. The higher the risk, the more likely it is linked to a fraudster, scammer, or other malicious actor trying to hide their identity. A medium risk can indicate a legitimate user with accounts on questionable platforms or recent appearance on data breaches (and potentially a victim of identity theft or account takeover)."},"wasRecentlyLeaked":{"type":"boolean","nullable":true,"description":"A flag that indicates whether this identity factor was recently leaked or appeared on a data breach in the past 6 months and could be a potential victim of identity theft or account takeover. This value is only available under deep search, null for quick search."},"footprintTenureInYears":{"type":"number","nullable":true,"description":"The potential tenure of this identity factor in years, measured from the first appearance on data breaches or data leaks. Please note that this is an estimate and may not be accurate, and the tenure indicates how old the identity factor is, but not necessarily that the same user owns it (victims of identity theft or account takeover may have their data stolen). This value is only available under deep search, null for quick search."},"probabilityOfPersonalUsage":{"type":"string","enum":["low","medium","high","very_high"],"nullable":false,"description":"The probability that this identity factor is used for personal purposes (e.g., entertainment, social)."},"probabilityOfWorkUsage":{"type":"string","enum":["low","medium","high","very_high"],"nullable":false,"description":"The probability that this identity factor is used for work purposes (e.g., professional tools, work-related platforms)."}},"required":["totalAssociatedServices","associatedServicesByCategory","servicesWithoutAssociation","riskLevel","wasRecentlyLeaked","footprintTenureInYears","probabilityOfPersonalUsage","probabilityOfWorkUsage"]},"DigitalFootprintStats":{"type":"object","properties":{"email":{"nullable":true,"description":"Statistics and analysis for the digital footprint linked to the email used for the search. Null if an email was not sent as part of the request.","allOf":[{"$ref":"#/components/schemas/IdentityFactorFootprintStats"}]},"phone":{"nullable":true,"description":"Statistics and analysis for the digital footprint linked to the phone number used for the search. Null if a phone number was not sent as part of the request.","allOf":[{"$ref":"#/components/schemas/IdentityFactorFootprintStats"}]},"allPlusInference":{"nullable":false,"description":"Statistics for all identity factors combined, including those platforms and digital footprint details found through inference. When a single identity factor is used and deep search is disabled, this object might be identical to the corresponding identity factor stats object. Quick search will not include inference data.","allOf":[{"$ref":"#/components/schemas/IdentityFactorFootprintStats"}]}},"required":["email","phone","allPlusInference"]},"SocialMediaDetails":{"type":"object","properties":{"numOfConnections":{"type":"string","nullable":true,"description":"A string indicating the number of friends or connections, if available. Please note that this is value is a string and might return values such as '500+' to indicate ranges and thresholds. Supported platforms (Deep search only): LinkedIn, TikTok."},"numOfFollowers":{"type":"number","nullable":true,"description":"The number of accounts following this account, if available. Supported platforms (Deep search only): Facebook, Instagram, LinkedIn, YouTube, Twitter/X, GitHub, TikTok."},"following":{"type":"number","nullable":true,"description":"The number of accounts this profile follows, if available. Supported platforms (Deep search only): Instagram, Twitter/X, GitHub, TikTok."},"isBusinessAccount":{"type":"boolean","nullable":true,"description":"A flag indicating that the account is a business profile, if known. Supported platforms (all search types): WhatsApp. Supported platforms (Deep search only): Instagram, TikTok."},"isVerified":{"type":"boolean","nullable":true,"description":"A flag indicating that the account is verified on the platform, if available. Supported platforms (Deep search only): Instagram, Twitter/X, Telegram, TikTok."},"numOfPosts":{"type":"number","nullable":true,"description":"The number of posts or pieces of content shared by this account, if available. Supported platforms (Deep search only): Instagram, Twitter/X, Google (GMaps posts), GitHub, TikTok."},"numOfInteractions":{"type":"number","nullable":true,"description":"The number of public interaction from this account (e.g., likes, lists), if available. Supported platforms (Deep search only): Twitter/X, TikTok."},"isPremium":{"type":"boolean","nullable":true,"description":"A flag indicating that the account is paying for a premium subscription (e.g. Twitter Blue), if available. Supported platforms (Deep search only): Twitter/X, Telegram, Flickr."},"isAdult":{"type":"boolean","nullable":true,"description":"A flag indicating that the account owner is an adult, if available. False if the account is associated to a minor (<18 years old). Supported platforms (Deep search only): TikTok."}},"required":["numOfConnections","numOfFollowers","following","isBusinessAccount","isVerified","numOfPosts","numOfInteractions","isPremium","isAdult"]},"MessagingAppDetails":{"type":"object","properties":{"canBeCalled":{"type":"boolean","nullable":true,"description":"A flag determining if the account can receive audio calls, if available. Supported platforms (Deep search only): Telegram."},"canReceiveVideoCalls":{"type":"boolean","nullable":true,"description":"A flag determining if the account can receive video calls, if available. Supported platforms (Deep search only): Telegram."},"isBanned":{"type":"boolean","nullable":true,"description":"A flag determining if the account has been banned, if available. Supported platforms (Deep search only): Telegram."},"markedAsFake":{"type":"boolean","nullable":true,"description":"A flag determining if the account has been marked as fake, a bot, or impersonator, if available. Supported platforms (Deep search only): Telegram."},"markedAsSpam":{"type":"boolean","nullable":true,"description":"A flag determining if the account has been marked as spam, if available. Supported platforms (Deep search only): Telegram."},"lastActivity":{"format":"date-time","type":"string","nullable":true,"description":"The timestamp (ISO8601) of the account's last known activity, if available. Supported platforms (all search types): Telegram."},"status":{"type":"string","nullable":true,"description":"The account's last known status, if available at the time of search. Possible values: ActiveRecently, ActiveLastWeek, ActiveLastMonth, Empty/Unknown, Offline, Online. Supported platforms (Deep search only): Telegram."},"isPrivateProfile":{"type":"boolean","nullable":true,"description":"Indicates if the profile is publicly visible or not, per its privacy settings. Supported platforms (all search types): Telegram, WhatsApp."}},"required":["canBeCalled","canReceiveVideoCalls","isBanned","markedAsFake","markedAsSpam","lastActivity","status","isPrivateProfile"]},"SocialMediaLocations":{"type":"object","properties":{"setByUser":{"type":"string","nullable":true,"description":"A string containing a location selected by the user, if available. Supported platforms (all search types): Gravatar. Supported platforms (Deep search only): Paypal, GitHub, Facebook, LinkedIn, MySpace, Gravatar, Flickr."},"placeOfOrigin":{"type":"string","nullable":true,"description":"A string containing a location selected by the user as their birthplace or hometown, if available. Supported platforms (Deep search only): Facebook."}},"required":["setByUser","placeOfOrigin"]},"DigitalFootprintCompany":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The organization's name."},"profileUrl":{"type":"string","nullable":true,"description":"The organization's social media profile URL."},"id":{"type":"string","nullable":true,"description":"The organization's social media ID."},"logoUrl":{"type":"string","nullable":true,"description":"The organization's logo URL."},"size":{"type":"string","nullable":true,"description":"The size of organization's measured as number of employeees; this is string is usually a range (e.g, '2-10' or 10,001+), so it is unsafe to parse as a number."}},"required":["name","profileUrl","id","logoUrl","size"]},"EmploymentHistoryItem":{"type":"object","properties":{"company":{"nullable":true,"description":"The company or organization associated to this work experience item.","allOf":[{"$ref":"#/components/schemas/DigitalFootprintCompany"}]},"location":{"type":"string","nullable":true,"description":"A string describing the location for position."},"position":{"type":"string","nullable":true,"description":"The position that the person held at this organization."},"startDate":{"type":"string","nullable":true,"description":"The user-reported time when the person was awarded this position; null if unknown. This date string can be a year or a month and a year, depending on how the user set this information on their profile."},"endDate":{"type":"string","nullable":true,"description":"The user-reported time when the person was stopped having this position; null if unknown. This date string can be a year or a month and a year, depending on how the user set this information on their profile."},"industries":{"nullable":true,"description":"A string array containing the industries in which this organization operates.","type":"array","items":{"type":"string"}},"description":{"type":"string","nullable":true,"description":"The user-generated descriptions of their activies, resposibilities and achievements in this position."}},"required":["company","location","position","startDate","endDate","industries","description"]},"ProfessionalDetails":{"type":"object","properties":{"employed":{"type":"boolean","nullable":true,"description":"An inferrence of whether the person linked to the provided email and/or phone is employed; based on their digital footprint; null if inconclusive."},"currentCompany":{"type":"string","nullable":true,"description":"An inferrence of the person's current employer; based on their digital footprint; null if inconclusive."},"currentPosition":{"type":"string","nullable":true,"description":"An inferrence of the person's current position; based on their digital footprint; null if inconclusive."},"industry":{"type":"string","nullable":true,"description":"The user-selected industry of their professional activities."},"workLocation":{"type":"string","nullable":true,"description":"The user-selected place of their professional activities."},"lastPositionDurationInMonths":{"type":"number","nullable":true,"description":"An inferrence of the duration of the person's last position in months; based on their digital footprint; null if inconclusive."},"totalExperienceInYears":{"type":"number","nullable":true,"description":"An inferrence of the person's total years of experience; based on their digital footprint; null if inconclusive."},"employmentHistory":{"nullable":false,"description":"A list of user-reported work experience including positions and organizations.","type":"array","items":{"$ref":"#/components/schemas/EmploymentHistoryItem"}}},"required":["employed","currentCompany","currentPosition","industry","workLocation","lastPositionDurationInMonths","totalExperienceInYears","employmentHistory"]},"EducationalInstitution":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The educational institution's name."},"logoUrl":{"type":"string","nullable":true,"description":"The educational institution's logo URL."},"profileUrl":{"type":"string","nullable":true,"description":"The educational institution's social media profile URL."}},"required":["name","logoUrl","profileUrl"]},"EducationHistoryItem":{"type":"object","properties":{"institution":{"nullable":false,"description":"An object containing the details of the associated educational institution, school, college, or university.","allOf":[{"$ref":"#/components/schemas/EducationalInstitution"}]},"degree":{"type":"string","nullable":true,"description":"The user-reported degree obtained from an educational institution."},"fieldOfStudy":{"type":"string","nullable":true,"description":"The user-reported academic discipline, field, or specific area of knowledge/expertise associated to the studies."},"startDate":{"type":"string","nullable":true,"description":"The start date of the studies; null if unknown. This date string can be a year or a month and a year, depending on how the user set this information on their profile."},"endDate":{"type":"string","nullable":true,"description":"The end date of the studies; null if unknown. This date string can be a year or a month and a year, depending on how the user set this information on their profile."},"activities":{"type":"string","nullable":true,"description":"The user-reported academic activities perfomed during the studies."},"description":{"type":"string","nullable":true,"description":"A user-generated description of their studies."}},"required":["institution","degree","fieldOfStudy","startDate","endDate","activities","description"]},"AccountDetails":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"The account's unique identifier, if public or known. Supported platforms (Deep search only): Twitter/X, Instagram, Google, GitHub, Telegram, TikTok, MySpace."},"createdAt":{"format":"date-time","type":"string","nullable":true,"description":"The account's creation date (ISO8601), if public or known. Supported platforms (Deep search only): Blogger, Duolingo , YouTube, OnlyFans, Facebook, Google, GitHub, LinkedIn, TikTok."},"updatedAt":{"format":"date-time","type":"string","nullable":true,"description":"Timestamp (ISO8601) of the last time the account was updated, if public or known. Supported platforms (Deep search only): GitHub."},"username":{"type":"string","nullable":true,"description":"The user selected handle or account name, if public or known. Supported platforms (all search types): Duolingo, WhatsApp, Flickr, Gravatar. Supported platforms (Deep search only): Twitter/X, Instagram, Facebook, Google, GitHub, Telegram, LinkedIn, TikTok, MySpace."},"fullName":{"type":"string","nullable":true,"description":"The account owner's name (usually a real name and not a nickname), if public or known. Supported platforms (all search types): Facebook, Gravatar, Google. Supported platforms (Deep search only): YouTube, Paypal, Twitter/X, Instagram, Flickr, GitHub, Telegram, LinkedIn, TikTok, MySpace"},"alias":{"type":"string","nullable":true,"description":"Alternative usernames, nicknames or names linked to the account, if public or known. Supported platforms (Deep search only): YouTube, Flickr, GitHub, MySpace"},"url":{"type":"string","nullable":true,"description":"The account's public link, if public or known. Supported platforms (all search types): Gravatar, Facebook. Supported platforms (Deep search only): YouTube, Twitter/X, Instagram, Flickr, GitHub, LinkedIn, TikTok, MySpace."},"photoUrl":{"type":"string","nullable":true,"description":"The account's profile image link, if available. Supported platforms (all search types): Duolingo, WhatsApp, Facebook, Google, Telegram. Supported platforms (Deep search only): YouTube, Twitter/X, Instagram, Flickr, Gravatar, GitHub, LinkedIn, TikTok, MySpace."},"bio":{"type":"string","nullable":true,"description":"The account's biography or the description written by the user, if available. Supported platforms (all search types): WhatsApp. Supported platforms (Deep search only): GitHub, Telegram, LinkedIn, TikTok, MySpace."},"headline":{"type":"string","nullable":true,"description":"The user-set tagline, usually shown as profile subtitle or short description, if available. Supported platforms (Deep search only): LinkedIn."},"confidence":{"type":"number","nullable":true,"description":"The likelihood of the profile matching the provided email and/or phone number from 0 to 100. This value is used when multiple accounts were found (best match is always returned) or an inference was made; null can be assumed as 100. This value is used only in deep search for these platforms: YouTube, Twitter/X, Facebook, Instagram, LinkedIn, TikTok."},"gender":{"type":"string","nullable":true,"description":"The user's gender, per their account's profile, if available. Possible values: male, female. Supported platforms (Deep search only): Google."},"social":{"nullable":true,"description":"An object that describes the account in terms of social media interactions and usage, if available. Supported platforms (all search types): WhatsApp. Supported platforms (Deep search only): Facebook, Instagram, LinkedIn, YouTube, Twitter/X, Telegram, Flickr, Google (public Maps interactions), GitHub, TikTok.","allOf":[{"$ref":"#/components/schemas/SocialMediaDetails"}]},"messaging":{"nullable":true,"description":"An object linked to messaging services that describes the account's activity and status, if available. Supported platforms (all search types): WhatsApp. Supported platforms (Deep search only): Telegram.","allOf":[{"$ref":"#/components/schemas/MessagingAppDetails"}]},"locations":{"nullable":true,"description":"An object containing locations associated to the account or set by the user, if available. Supported platforms (all search types): Gravatar. Supported platforms (Deep search only): Paypal, GitHub, Facebook, LinkedIn, MySpace, Gravatar, Flickr.","allOf":[{"$ref":"#/components/schemas/SocialMediaLocations"}]},"professionalInfo":{"nullable":true,"description":"An array of objects describing the user's work history, if available. Supported platforms (Deep search only): LinkedIn.","allOf":[{"$ref":"#/components/schemas/ProfessionalDetails"}]},"educationHistory":{"nullable":true,"description":"An array of objects describing the user's education history, if available. Supported platforms (Deep search only): LinkedIn.","type":"array","items":{"$ref":"#/components/schemas/EducationHistoryItem"}}},"required":["id","createdAt","updatedAt","username","fullName","alias","url","photoUrl","bio","headline","confidence","gender","social","messaging","locations","professionalInfo","educationHistory"]},"AccountMatch":{"type":"object","properties":{"siteOrService":{"type":"string","nullable":false,"description":"A string label identifying the website, app, or platform where the phone and/or email was looked for. Possible values by search type:\n\nQuick search:\nAdobe, AirVpn, Amazon, Apple, Asana, Atlassian, Babbel, CabifyDriver, Cinemex, Clip.mx, Codecademy, Disney+, Dropbox, Duolingo, Facebook, Firefox, Flickr, GitHub, Google, Gravatar, Hubspot, Instagram, Microsoft, Patreon, Pinterest, Quora, Rappi, Replit, Samsung, Spotify, TED, Trello, Trivago, Twitter/X, Vimeo, WhatsApp, WordPress, Yahoo, Zoho.\n\nDeep search only:\n1Win, 8Fit, AboutMe, Adobe, AirVpn, AliExpress, Alibaba, Amazon, Americanas, Animoto, AnyDo, Apollo, Apple, Aptoide, Asana, Atlassian, Babbel, Badoo, Bitmoji, BlaBlaCar, Blip, Blogger, BlueGrassRivals, BodyBuilding, BuyMeACoffee, CabifyDriver, Canva, Chegg, Chess.com, Cinemex, ClearVoiceSurveys, Clip.mx, CodePen, Codecademy, CoinMarketCap, CoinTracker, Coinmama, Coroflot, Crevado, CutoutPro, DailyMotion, DevRant, Diigo, Discord, Disney+, Docker, Dropbox, Duolingo, Ebay, Ello, Envato, Etsy, Eventbrite, Evernote, Evite, Eyeem, Facebook, Firefox, Flickr, Freelancer, Garmin, Gemini, GitHub, Gitlab, Google, Gravatar, Hubspot, Instagram, Issuu, Jefit, JobAndTalent, KickStarter, KodiTV, Komoot, LastFM, LastPass, LinkedIn, MercadoLibre, Microsoft, MovieBoxPro, MyFitnessPal, MyHeritage, MySpace, Nike, Office365, OnlyFans, Parler, Patreon, PayPal, Pinterest, PipeDrive, Pizap, PornHub, ProtonMail, QuestionPro, Quora, Rappi, RedTube, Reddit, Replit, Romwe, Samsung, Shopee, Smule, Snapchat, SoundCloud, Spotify, StockX, Strava, SurveyLama, TED, Telegram, TikTok, Tinder, Trello, TripAdvisor, Trivago, Tumblr, TuneFind, Twitter/X, Venmo, Vimeo, VivaAir, Vivino, VoxMedia, Vrbo, Vsco, Wattpad, WhatsApp, WordPress, XVideos, Xnxx, Yahoo, YouTube, Zoho"},"accountExists":{"type":"boolean","nullable":false,"description":"A boolean value that determines whether and account is linked to the email and/or phone number. Only high-confidence data is returned; a false value means the phone and/or email is NOT registered in the site, if the result is unknown or failed to be obtained, the platform is ommited from the list altogether."},"categories":{"nullable":false,"description":"A list of strings that describes the type of website, app, or platform where the phone and/or email was looked for. Possible values: adult, blogging, business, creative, crypto, dating, delivery, design, ecommerce, education, email_service, employment, entertainment, events, finance, freelancing, gambling, gig_economy, messaging, news, social_media, software_engineering, sports, streaming, technology, travel, utilities, work_tools","type":"array","items":{"type":"string"}},"inputsUsed":{"type":"array","nullable":false,"description":"An array that indicates whether email and/or phone number was used to obtain this account information. In some cases, both elements are used or inference is made based on previously available data (particularly common in deep search).","items":{"type":"string","enum":["email","phone","inference"]}},"details":{"nullable":true,"description":"An object containing details of the account linked to the email or phone number, if any was found; the availability of this object and its contents depends on the website, app, or platform queried and the type search used (deep search usually yields more information). Null if the details are unknown or were unavailable at search time.","allOf":[{"$ref":"#/components/schemas/AccountDetails"}]}},"required":["siteOrService","accountExists","categories","inputsUsed","details"]},"DataLeakDetails":{"type":"object","properties":{"firstMatch":{"format":"date-time","type":"string","nullable":true,"description":"The timestamp (ISO8601) of the oldest data leak. Null if no breaches were found."},"lastMatch":{"format":"date-time","type":"string","nullable":true,"description":"The timestamp (ISO8601) of the most recent data leak. Null if no breaches were found."},"total":{"type":"number","nullable":false,"description":"The number of data leaks found for both the email and phone number provided."},"listOfLeaks":{"nullable":false,"description":"A list of strings containing the name of each data leak and the time it happened in the format: '{breachName} ({breachDate})'.","type":"array","items":{"type":"string"}}},"required":["firstMatch","lastMatch","total","listOfLeaks"]},"DataLeakWrapper":{"type":"object","properties":{"firstMatch":{"format":"date-time","type":"string","nullable":true,"description":"The timestamp (ISO8601) of the oldest data leak for both the email and phone number provided. Null if no breaches were found."},"lastMatch":{"format":"date-time","type":"string","nullable":true,"description":"The timestamp (ISO8601) of the most recent data leak for both the email and phone number provided. Null if no breaches were found."},"numOfLeaks":{"type":"number","nullable":false,"description":"The number of data leaks found for both the email and phone number provided."},"linkedToPhoneNumber":{"nullable":true,"description":"The list of data leaks linked to the provided phone number; null if none was provided or no breaches were found.","allOf":[{"$ref":"#/components/schemas/DataLeakDetails"}]},"linkedToEmail":{"nullable":true,"description":"The list of data leaks linked to the provided email; null if none was provided or no breaches were found.","allOf":[{"$ref":"#/components/schemas/DataLeakDetails"}]}},"required":["firstMatch","lastMatch","numOfLeaks","linkedToPhoneNumber","linkedToEmail"]},"DigitalFootprintResult":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"stats":{"nullable":false,"description":"An object containing statistics about the digital footprint search results and some recommendations regarding the level of risk of the associated user.","allOf":[{"$ref":"#/components/schemas/DigitalFootprintStats"}]},"accountMatches":{"nullable":false,"description":"An array of accounts that matched the phone number and/or email provided. Please note that although we search in hundreds of websites, apps, and platforms, we only return information we are highly confident in. As such, if we return that the profile DOES NOT have an account, we are highly certain of it. Moreover, if deep search is used, we can return extensive details of each account, but please be aware that data availability varies and fields can be empty at any point.","type":"array","items":{"$ref":"#/components/schemas/AccountMatch"}},"dataLeaks":{"nullable":true,"description":"When running a deep search, we'll return some basic information about data leaks that were found for this email and phone combination. This is helpful to estimate the age of the identity factor and the its usage level over the years. Null for quick search.","allOf":[{"$ref":"#/components/schemas/DataLeakWrapper"}]}},"required":["stats","accountMatches","dataLeaks"]},"CarrierScoreConfiguration":{"type":"object","properties":{"returnAllScores":{"type":"boolean","description":"If true, all scores will be returned, regardless of other configuration objects. If false, this flag is ignored and only the scores specified in `selectedScores` will be returned. The request will be rejected if a premium package is requested and both `returnAllScores` and `selectedScores` are empty, missing or null."},"requestedScores":{"type":"array","nullable":false,"description":"The list of carrier-generated scores to return for the phone number. Values should not be repeated and must not include unexpected values. Please note that when requesting a singles score, you can also request a fallback by adding it to the array when using the prepaid and postpaid scores; for example, if you want a prepaid score but the phone number is under a postpaid plan, you can add another postpaid score to the list as a fallback; same goes for postpaid scores. Note that you cannot request a general-availability score as a fallback (doing so will result in a request rejection). Furthermore, depending on the carrier, some scores might be sold as bundles, so some configurations might not be possible. Supported carrier constraints:\n\n - [MX] Telcel: scores can be requested in three types of bundles: single score (1 general-availability score or 1 prepaid/postpaid score with a fallback), medium bundle (fraud and risk score + 3 other variables) and full-package (all scores).","items":{"type":"string","enum":["activityLevel","simCardChangeRate","usageTrend","contactNetwork","userRating","reachabilityScore","techAdoption","fraudScore","riskScore","postpaid-usageLevel","postpaid-creditLimit","postpaid-hasDirectDebit","prepaid-topUpVolume","prepaid-topUpFrequency"]}}}},"PhoneInsightsConfiguration":{"type":"object","properties":{"carrierScores":{"nullable":true,"description":"An object used to configure the carrier-generated scores that will be returned. This includes the configuration of fallbacks, in case a score is not available. Please note that your request might be rejected if the configuration doesn't meet the acceptable criteria.","allOf":[{"$ref":"#/components/schemas/CarrierScoreConfiguration"}]}}},"PhoneInsightsRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"dataPackages":{"type":"array","nullable":false,"description":"The desired data bundles to return in the form of a string array, please consider that this is directly linked to pricing and omitting a package will return some fields as null. Morever, including a package might increase the cost of your request and make it slower (as more data is queried and generated). Contact your sales representative for more details.","items":{"type":"string","enum":["standard","pro","premium"]}},"phoneNumber":{"nullable":true,"description":"The phone number to obtain insights from. It can be provided as a string in E.164 format (e.g., +14155552671) or an object containing the country code and number separately.","allOf":[{"$ref":"#/components/schemas/PolymorphicInputPhone"}]},"configuration":{"nullable":true,"description":"An object used to configure the data to return. Mandatory for the premium package, ignored for others.","allOf":[{"$ref":"#/components/schemas/PhoneInsightsConfiguration"}]}},"required":["dataPackages","phoneNumber"]},"ServiceProvider":{"type":"object","properties":{"legalName":{"type":"string","description":"Legal name of the service provider."},"brandName":{"type":"string","nullable":true,"description":"Brand or public name of the service provider."},"isRetail":{"type":"boolean","nullable":true,"description":"True if the service provider serves end-consumers. Null if unknown."},"isB2B":{"type":"boolean","nullable":true,"description":"True if the service provider serves companies. Null if unknown."},"sellsVirtualNumbers":{"type":"boolean","nullable":true,"description":"True if the service provider sells virtual numbers. Null if unknown."},"sellsSatellitePhones":{"type":"boolean","nullable":true,"description":"True if the service provider sells satellite telephony. Null if unknown."},"isWhiteLabel":{"type":"boolean","nullable":true,"description":"True if the service provider sells white-label telephony or is B2B2C. Null if unknown."},"sellsIPTelephony":{"type":"boolean","nullable":true,"description":"True if the service provider sells IP Telephony. Null if unknown."},"sellsVoIP":{"type":"boolean","nullable":true,"description":"True if the service provider sells VoIP services. Null if unknown."},"sellsVoLTE":{"type":"boolean","nullable":true,"description":"True if the service provider sells VoLTE services. Null if unknown."},"mobileCountryCode":{"type":"string","nullable":true,"description":"The mobile country code (MCC) linked to the carrier."},"mobileNetworkCode":{"type":"string","nullable":true,"description":"The mobile network code (MNC) linked to the carrier."}},"required":["legalName","brandName","isRetail","isB2B","sellsVirtualNumbers","sellsSatellitePhones","isWhiteLabel","sellsIPTelephony","sellsVoIP","sellsVoLTE","mobileCountryCode","mobileNetworkCode"]},"PlaceOfRegistration":{"type":"object","properties":{"locality":{"type":"string","description":"Locality where the phone number was registered."},"municipality":{"type":"string","description":"Municipality where the phone number was registered."},"state":{"type":"string","description":"State or equivalent where the phone number was registered."}},"required":["locality","municipality","state"]},"NumberLiveDataTier1":{"type":"object","properties":{"isValid":{"type":"string","nullable":true,"description":"Determines if the phone number is valid, in terms of structure, potential carrier allocation, and country code rules. Nullable if validity couldn't be determined. Possible values: valid, length_too_short, length_too_long, incorrect_format, invalid_unallocated, invalid_country_code, invalid. Warning: validity is not verification. If you want to verify that a number is in possession of a user, you'll need to use OTPs (Traditional or Inverse); visit our SDK documentation for more info on how to do so: https://developer.veriph.one/docs/intro"},"isActive":{"type":"string","nullable":true,"description":"A live status query to the carrier to determine if the phone number is active and reachable. This value will be null if the number is invalid. Possible values: active, disconnected (active, but currently turned off or without signal), inactive (unassigned to a user), other (neither inactive nor absent. Usually a temporary status that might indicate a transition), unavailable (carrier is down or rejected the request)"}},"required":["isValid","isActive"]},"NumberLiveDataTier2":{"type":"object","properties":{"isVoIp":{"type":"boolean","nullable":true,"description":"True is this number is a VoIP (Voice Over Internet Protocol) or a virtual phone number. Null if unknown."},"isPrepaid":{"type":"boolean","nullable":true,"description":"True if this phone has a prepaid service plan, null if unknown. This data is inferred and might be incorrect or outdated. For high-precision, live updates, check out Live phone number data (Tier 3)."},"lineSubtype":{"type":"number","nullable":true,"description":"Subtype of phone number. Nullable if number is invalid or the subtype is not specified by the carrier. This field has limited availability. Possible values: Mobile Generic [100], VoLTE [200], VoIP [300], Pager [400], Mobile Caller-Party-Pays [1000], Mobile Receiver-Party-Pays [2000], Landline [3000], Satellite [10000], SharedCharges [20000], PersonalWithCallTransfer [30000], ReverseCharges [40000], Surcharges [50000], Premium Rate [60000], Toll-Free [70000], Unknown [null]."},"listedOnDNC":{"type":"boolean","nullable":true,"description":"True if the number is listed on any Do Not Call (DNC) lists. USA & Canada only. Data is not live, and might take some time for latest information to show up."}},"required":["isVoIp","isPrepaid","lineSubtype","listedOnDNC"]},"NumberPortability":{"type":"object","properties":{"portsInLastThreeYears":{"type":"number","nullable":true,"description":"Number of portability events for the phone number in the past 1,095 days. Null if number is invalid."},"wasPorted":{"type":"boolean","nullable":true,"description":"True if the number has been ported at some point. Null if number is invalid."},"originalCarrier":{"nullable":true,"description":"The carrier this number original belonged to; object of type: @serviceProvider. Null if the number wasn't ported, the country doesn't support portability or the number is invalid.","allOf":[{"$ref":"#/components/schemas/ServiceProvider"}]}},"required":["portsInLastThreeYears","wasPorted","originalCarrier"]},"RiskAndFraudScoring":{"type":"object","properties":{"fraudScore":{"type":"number","nullable":true,"description":"Measures how likely a phone number is to be fraudulent in a range between 0 and 100. The higher the more likely it is a fraudster. ≥75 is suspicious due to reputation issues, fraud reports, or usage of a low risk proxy/VPN. ≥85 is risky because of multiple signs of anomalous behavior and likely to be malicious. ≥90 is high risk linked to frequent abusive behavior or has shown fraud signals in the past 24 to 72 hours."},"recentAbuse":{"type":"boolean","nullable":true,"description":"True if this number been linked to recent or ongoing fraud."},"isRisky":{"type":"boolean","nullable":true,"description":"True if the number has reports of fraudulent activity, scams, robocalls, fake accounts, or similar malicious behavior."},"wasLeaked":{"type":"boolean","nullable":true,"description":"True if the number was recently exposed in an online database breach or compromise."},"reportedAsSpam":{"type":"boolean","nullable":true,"description":"True if the number has recently been reported for spam or harassing calls/SMS."}},"required":["fraudScore","recentAbuse","isRisky","wasLeaked","reportedAsSpam"]},"AssociatedIdentities":{"type":"object","properties":{"knownNames":{"nullable":false,"description":"An array of inferred names of the possible owner(s) of the phone number. This field doesn't come from carrier provided data and might be incorrect or unavailable. If the number is owned by a person, we return they first or last name; if its owned by a business, the company's name. or business name assigned to the phone number.","type":"array","items":{"type":"string"}},"associatedEmails":{"nullable":false,"description":"An array of known emails linked to this phone number, if any. Availability of this data varies by country.","type":"array","items":{"type":"string"}}},"required":["knownNames","associatedEmails"]},"LinkedIpAddress":{"type":"object","properties":{"ipAddress":{"type":"string","description":"The IP address linked to the phone number. Can be either IPv4 or IPv6."},"metadata":{"type":"object","nullable":true,"description":"A payload including the details of the linked IP address at the time of the association. See IP address metadata for details on its properties. On v1.2.0 of the API, this value will be null; the field will be we filled on a later version."},"dateOfLastUsage":{"format":"date-time","type":"string","description":"The date and the last time the phone number used this IP address."},"usageCount":{"type":"number","description":"How many times has this particular IP address used this phone number."}},"required":["ipAddress","metadata","dateOfLastUsage","usageCount"]},"LinkedIpAddresses":{"type":"object","properties":{"dateOfFirstAppearance":{"format":"date-time","type":"string","nullable":true,"description":"First date-time (ISO8601) a number was linked to an IP address on the Veriph.One platform. Null if the number has no known linked IP addresses."},"associatedIpAddresses":{"nullable":false,"description":"A list of IP addresses linked to this phone number.","type":"array","items":{"$ref":"#/components/schemas/LinkedIpAddress"}}},"required":["dateOfFirstAppearance","associatedIpAddresses"]},"PostpaidInsights":{"type":"object","properties":{"usageLevel":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Categorization of the user's average monthly consumption level. 1 represents basic consumption (low-volume user), while 10000 represents premium consumption (high-volume user)."},"creditLimit":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Classification of the credit limit assigned to the user's contracted plan. 1 represents a basic credit limit, while 10000 represents a premium credit limit."},"hasDirectDebit":{"type":"boolean","nullable":true,"description":"Binary indicator of the configured payment method. True if the user has direct-debit payments enabled (automatically charged to their credit/debit cards, savings, payroll, or checking accounts). Users with direct debit configured tend to show lower risk of non-payment."}},"required":["usageLevel","creditLimit","hasDirectDebit"]},"PrepaidInsights":{"type":"object","properties":{"topUpVolume":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Evaluation of recharge behavior based on historical amounts. Considers average recharge amount, consistency in amounts, and growth trend. 1 represents low recharge capacity, while 10000 represents high recharge capacity. Value is a score, not currency."},"topUpFrequency":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Analysis of regularity and predictability in recharge behavior. Considers recharge frequency, temporal consistency, and amount variability. 1 represents low regularity (no or very infrequent top-ups), while 10000 represents high regularity (very frequent and consistent top-ups)."}},"required":["topUpVolume","topUpFrequency"]},"FraudLikelihoodInsight":{"type":"object","properties":{"level":{"type":"string","enum":["very_low","low","moderate","high","very_high"],"nullable":true,"example":"low","description":"Categorical assessment of the likelihood that the phone line is associated with fraudulent behavior. Derived primarily from the carrier-reported fraud score, SIM card change frequency, and behavioral risk flags. Low activity and a small contact network raise the likelihood, while stable usage patterns reduce it. Null when insufficient data is available to produce a reliable classification."},"confidence":{"type":"string","enum":["high","moderate","low","insufficient_data"],"example":"high","description":"Indicates how reliable the fraud likelihood level is. High when the carrier-reported fraud score is available; moderate or low when the assessment relies on indirect behavioral signals; insufficient_data when key inputs are missing."}},"required":["level","confidence"]},"CreditRiskInsight":{"type":"object","properties":{"level":{"type":"string","enum":["very_low","low","moderate","high","very_high"],"nullable":true,"example":"low","description":"Categorical assessment of the subscriber's risk of non-payment. For postpaid lines, considers the carrier-reported risk score, credit limit, direct-debit status, usage level, user rating, and contact network size. For prepaid lines, considers the risk score, user rating, reachability, contact network, and activity level. Higher credit limits, direct-debit enrollment, and strong user ratings reduce risk; low engagement and poor payment indicators raise it. Null when insufficient data is available."},"confidence":{"type":"string","enum":["high","moderate","low","insufficient_data"],"example":"high","description":"Indicates how reliable the credit risk level is. Confidence increases with the number of available input signals and is highest when the carrier-reported risk score is present."}},"required":["level","confidence"]},"IdentityConfidenceInsight":{"type":"object","properties":{"level":{"type":"string","enum":["high","moderate","low"],"nullable":true,"example":"high","description":"Estimates how likely the phone line is operated by a real, consistent individual rather than a synthetic or transient identity. Considers SIM stability (frequent changes reduce confidence), reachability, user rating, activity level, contact network breadth, and plan-specific engagement (top-up frequency for prepaid, usage level for postpaid). Null when fewer than three primary signals are available."},"confidence":{"type":"string","enum":["high","moderate","low","insufficient_data"],"example":"high","description":"Indicates how reliable the identity confidence level is. High when sufficient primary signals are available; insufficient_data otherwise."}},"required":["level","confidence"]},"RiskAssessment":{"type":"object","properties":{"fraudLikelihood":{"description":"Assesses the probability of fraudulent behavior associated with the phone line. Combines carrier-reported fraud indicators with behavioral signals to produce a categorical level and confidence rating.","allOf":[{"$ref":"#/components/schemas/FraudLikelihoodInsight"}]},"creditRiskLevel":{"description":"Assesses the subscriber's likelihood of non-payment. Adapts its inputs to the plan type (postpaid vs. prepaid) and combines carrier risk data with financial and engagement signals.","allOf":[{"$ref":"#/components/schemas/CreditRiskInsight"}]},"realIdentityConfidence":{"description":"Estimates the likelihood that the phone line belongs to a real, consistent individual. Combines SIM stability, reachability, and engagement metrics to gauge identity authenticity.","allOf":[{"$ref":"#/components/schemas/IdentityConfidenceInsight"}]}},"required":["fraudLikelihood","creditRiskLevel","realIdentityConfidence"]},"SubscriberProfileInsight":{"type":"object","properties":{"profile":{"type":"string","enum":["premium_established","standard_active","basic_low_engagement","growing_user","declining_user","dormant_or_minimal"],"nullable":true,"example":"standard_active","description":"Classifies the subscriber into a behavioral profile based on their user rating, activity level, and usage trend. High-rated users with strong activity are classified as premium; growing usage trends with moderate ratings indicate an expanding user; very low activity or declining trends lead to a dormant classification. Null when user rating or activity level are unavailable."},"confidence":{"type":"string","enum":["high","moderate","low","insufficient_data"],"example":"high","description":"Indicates how reliable the subscriber profile classification is. High when both user rating and activity level are available; insufficient_data otherwise."}},"required":["profile","confidence"]},"FinancialCapacityInsight":{"type":"object","properties":{"level":{"type":"string","enum":["high","moderate","low","indeterminate"],"nullable":true,"example":"moderate","description":"Estimates the subscriber's financial capacity based on plan-specific signals. For postpaid lines, considers credit limit, usage level, direct-debit enrollment, technology adoption, user rating, contact network, and risk score. For prepaid lines, considers top-up volume, top-up frequency, technology adoption, user rating, contact network, and risk score. Higher credit limits, consistent top-ups, and strong user ratings raise the level; elevated risk scores reduce it. Indeterminate when key financial signals are missing."},"confidence":{"type":"string","enum":["high","moderate","low","insufficient_data"],"example":"high","description":"Indicates how reliable the financial capacity level is. Confidence increases with the number of available input signals; insufficient_data when critical financial indicators are absent."}},"required":["level","confidence"]},"TelcoReachabilityAnalysis":{"type":"object","properties":{"level":{"type":"string","enum":["highly_reachable","moderately_reachable","hard_to_reach"],"nullable":true,"example":"moderately_reachable","description":"Categorical assessment of the likelihood of successfully reaching the subscriber by phone. Primarily driven by the carrier-reported reachability score, with activity level and usage trend as supporting signals. High activity and growing usage trends improve reachability; declining trends reduce it. Null when the reachability score is unavailable."},"confidence":{"type":"string","enum":["high","moderate","low","insufficient_data"],"example":"high","description":"Indicates how reliable the reachability analysis is. High when the carrier-reported reachability score is present."}},"required":["level","confidence"]},"ProfileClassification":{"type":"object","properties":{"subscriberProfile":{"description":"Categorizes the subscriber into a behavioral profile (e.g., premium, standard, dormant) based on engagement intensity and tenure.","allOf":[{"$ref":"#/components/schemas/SubscriberProfileInsight"}]},"financialCapacityIndicator":{"description":"Estimates the subscriber's financial capacity using plan-specific spending and engagement signals.","allOf":[{"$ref":"#/components/schemas/FinancialCapacityInsight"}]},"reachabilityAnalysis":{"nullable":true,"description":"Predicts how likely the subscriber is to answer an inbound call, based on reachability, activity, and usage trend data. Null when the carrier-reported reachability score is unavailable.","allOf":[{"$ref":"#/components/schemas/TelcoReachabilityAnalysis"}]}},"required":["subscriberProfile","financialCapacityIndicator","reachabilityAnalysis"]},"BehavioralFlags":{"type":"object","properties":{"constantSimChange":{"type":"boolean","nullable":true,"example":false,"description":"True when the SIM card change rate exceeds the high-frequency threshold, which may signal device loss, account takeover, or suspicious activity. Null when SIM card change data is unavailable."},"decliningUsage":{"type":"boolean","nullable":true,"example":false,"description":"True when the usage trend falls below the declining threshold, indicating the subscriber's consumption is decreasing over the observation period. Null when usage trend data is unavailable."},"isHighValue":{"type":"boolean","nullable":true,"example":false,"description":"True when the subscriber qualifies as high-value based on user rating or credit limit, provided that fraud and risk scores remain below disqualifying thresholds. Null when none of the required inputs (fraud score, risk score, user rating, credit limit) are available."},"isLowValue":{"type":"boolean","nullable":true,"example":false,"description":"True when the user rating falls below the basic-tier threshold, indicating a new or low-engagement subscriber. Null when user rating is unavailable."},"lowReachability":{"type":"boolean","nullable":true,"example":false,"description":"True when the reachability score falls below the low-contact threshold, meaning the subscriber is unlikely to answer inbound calls. Null when reachability data is unavailable."},"rapidUsageGrowth":{"type":"boolean","nullable":true,"example":false,"description":"True when the usage trend exceeds the moderate-growth threshold and activity level is at least moderate, indicating an accelerating consumption pattern. Null when either usage trend or activity level data is unavailable."},"highTechProfile":{"type":"boolean","nullable":true,"example":false,"description":"True when technology adoption score meets or exceeds the high-adoption threshold, indicating use of modern networks (4G/5G), high-end devices, and active digital service consumption. Null when technology adoption data is unavailable."},"lowTechProfile":{"type":"boolean","nullable":true,"example":false,"description":"True when technology adoption score falls below the low-adoption threshold, indicating use of legacy networks (2G/3G), low-end devices, or minimal data usage. Always false if highTechProfile is true. Null when technology adoption data is unavailable."},"seemsRisky":{"type":"boolean","nullable":true,"example":false,"description":"Composite risk flag that is true when the subscriber is classified as low-value, or when plan-specific engagement indicators fall below minimum thresholds (low usage level for postpaid, low top-up frequency for prepaid). Null when none of the underlying signals are available."}},"required":["constantSimChange","decliningUsage","isHighValue","isLowValue","lowReachability","rapidUsageGrowth","highTechProfile","lowTechProfile","seemsRisky"]},"TelcoInsightsSummary":{"type":"object","properties":{"riskAssessment":{"description":"Groups fraud likelihood, credit risk, and identity confidence assessments. Use this section for decisioning around fraud prevention, credit underwriting, and identity verification.","allOf":[{"$ref":"#/components/schemas/RiskAssessment"}]},"profileClassification":{"description":"Groups subscriber profiling, financial capacity, and reachability analysis. Use this section for customer segmentation, creditworthiness estimation, and contact-strategy optimization.","allOf":[{"$ref":"#/components/schemas/ProfileClassification"}]},"behavioralFlags":{"description":"A set of boolean indicators derived from individual telco scores. Each flag highlights a specific behavioral trait (e.g., frequent SIM changes, declining usage, high value) for quick filtering and rule-based decisioning.","allOf":[{"$ref":"#/components/schemas/BehavioralFlags"}]}},"required":["riskAssessment","profileClassification","behavioralFlags"]},"TelcoScoringWithSummary":{"type":"object","properties":{"postpaidInsights":{"nullable":true,"description":"Variables and scores available for phone numbers associated with postpaid plans. Null if number is not postpaid or if not covered by your plan.","allOf":[{"$ref":"#/components/schemas/PostpaidInsights"}]},"prepaidInsights":{"nullable":true,"description":"Variables and scores available for phone numbers associated with prepaid plans. Null if number is not prepaid or if not covered by your plan.","allOf":[{"$ref":"#/components/schemas/PrepaidInsights"}]},"activityLevel":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Composite activity index that considers multiple communication channels: voice traffic (incoming/outgoing calls), SMS messaging, data consumption, and usage frequency. 1 means the user is inactive and uncommitted, while 10000 means the user is very active and committed. Null if not covered by your plan."},"simCardChangeRate":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Stability metric that evaluates the frequency of SIM card changes for a specific phone line since its activation. 1 means the user has not changed their SIM card, while 10000 means very frequent SIM card changes. High values may indicate frequent device loss, possible fraud or suspicious activity, or low user stability. Null if not covered by your plan."},"usageTrend":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Analyzes the evolution of the user's consumption pattern over the last two months. 1 represents decreasing consumption, while 10000 represents accelerated growth. Intermediate values indicate stable consumption or moderate growth. Null if not covered by your plan."},"contactNetwork":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Evaluates the size and diversity of the user's communication network. Considers the number of unique contacts, communication frequency, and geographic diversity. 1 represents a limited network with minimal interaction, while 10000 represents a broad and highly active network. Null if not covered by your plan."},"userRating":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Comprehensive classification of user value based on multiple dimensions. The algorithm weighs line tenure (highest weight in the model), payment stability, activity level, and plan segmentation. 1 represents a basic user (new or low-value), while 10000 represents a VIP user with maximum value and stability. Null if not covered by your plan."},"reachabilityScore":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Predicts the likelihood of successful phone contact based on behavior patterns. The model considers average response time, historical answer rate, activity schedules, and call forwarding configuration. 1 means low probability of contact, while 10000 means high probability of contact. Null if not covered by your plan."},"techAdoption":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Evaluates the user's level of technological sophistication across multiple dimensions: network type used (2G/3G/4G/5G), device tier, data consumption, application diversity, and digital services adoption. 1 represents low technology adoption (e.g., 2G/3G networks, low-end devices, or minimal data usage), while 10000 represents high adoption (4G/5G networks, high-end devices, high data consumption, and active use of digital services). Null if not covered by your plan."},"fraudScore":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Evaluates the likelihood of fraudulent behavior based on mobile usage patterns. 1 means low risk with consistent and reliable behavior, while 10000 means high risk with a highly suspicious behavior pattern. Null if not covered by your plan."},"riskScore":{"type":"number","nullable":true,"minimum":1,"maximum":10000,"description":"Comprehensive assessment of default risk based on historical mobile behavior. 1 means a reliable user with a solid payment history, while 10000 means high probability of default. Null if not covered by your plan."},"insightsSummary":{"nullable":true,"description":"An object containing a general-purpose analysis of the scores obtained from the carrier. Please note that its contents are highly dependent on the amount of data available (the number of scores requested and the availability of data). This field is currently in beta.","allOf":[{"$ref":"#/components/schemas/TelcoInsightsSummary"}]}},"required":["postpaidInsights","prepaidInsights","activityLevel","simCardChangeRate","usageTrend","contactNetwork","userRating","reachabilityScore","techAdoption","fraudScore","riskScore","insightsSummary"]},"VeriphOnePhoneInsightsResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"countryIsoCode3166_2":{"type":"string","nullable":false,"description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."},"phoneCode":{"type":"string","nullable":false,"description":"Phone code for this country; to be used as a preffix on a phone number."},"phoneNumber":{"type":"string","nullable":false,"description":"The provide phone number without country code."},"serviceProvider":{"nullable":true,"description":"Known information on the service provider currently servicing this phone number (including cases where the number was ported). Null if the number is invalid or information is unavailable.","allOf":[{"$ref":"#/components/schemas/ServiceProvider"}]},"placeOfRegistration":{"nullable":true,"description":"Details of the phone number if it is geographical; null otherwise. Available only for Mexico.","allOf":[{"$ref":"#/components/schemas/PlaceOfRegistration"}]},"lineType":{"type":"string","nullable":true,"description":"Type of phone number. Nullable if number is invalid or information in unavailable. Possible values: Wireless, Wireline, Service line."},"liveDataTier1":{"nullable":false,"description":"Current real-time qualities of the provided phone number.","allOf":[{"$ref":"#/components/schemas/NumberLiveDataTier1"}]},"liveDataTier2":{"nullable":true,"description":"Additional phone number metadata that uncovers the type of phone number interacting with your platform. Requires a Pro plan or higher, null otherwise.","allOf":[{"$ref":"#/components/schemas/NumberLiveDataTier2"}]},"portability":{"nullable":false,"description":"Information related to portability events on the phone number. Only available for wireless/mobile numbers.","allOf":[{"$ref":"#/components/schemas/NumberPortability"}]},"riskAndFraudScoring":{"nullable":true,"description":"A dataset that helps flag risky and potentially malicious phone numbers. Requires a Pro plan or higher, null otherwise.","allOf":[{"$ref":"#/components/schemas/RiskAndFraudScoring"}]},"associatedIdentities":{"nullable":true,"description":"[Feature in Beta] Known identities previously linked to the provided phone number. Requires a Pro plan or higher, null otherwise.","allOf":[{"$ref":"#/components/schemas/AssociatedIdentities"}]},"linkedIpAddresses":{"nullable":false,"description":"[Feature in Alpha] A dataset containing the IP address associated to a phone number and insights derived from such values.","allOf":[{"$ref":"#/components/schemas/LinkedIpAddresses"}]},"blacklistMatches":{"nullable":false,"description":"[Feature in Beta] Used to determine if the phone number is found on fraudster, scammer and public virtual number blacklists.","allOf":[{"$ref":"#/components/schemas/BlacklistMatches"}]},"knownCapabilities":{"nullable":false,"description":"[Feature in Alpha] Points of the interaction of this phone number with the Veriph.One platform or its data partners that show its current or past capabilities.","allOf":[{"$ref":"#/components/schemas/KnownCapabilities"}]},"telcoScoring":{"nullable":true,"description":"Telco scores and variables used to obtain carrier-generated insights about a phone number. Limited availability (currently only Telcel in Mexico). Only available in premium plan. Null if unsupported or not covered by your plan.","allOf":[{"$ref":"#/components/schemas/TelcoScoringWithSummary"}]}},"required":["countryIsoCode3166_2","phoneCode","phoneNumber","serviceProvider","placeOfRegistration","lineType","liveDataTier1","liveDataTier2","portability","riskAndFraudScoring","associatedIdentities","linkedIpAddresses","blacklistMatches","knownCapabilities","telcoScoring"]},"SmtpCheckConfiguration":{"type":"object","properties":{"timeoutInSeconds":{"type":"number","minimum":1,"maximum":60,"nullable":true,"description":"A value that governs how long the service will wait for the provided email's SMTP server to respond. Setting a high value can increase accuracy and provide better insights into reachability. To cover most servers with high accuracy, we recommend setting it within a 20- to 40-second range. If sent as null or omitted, the service will default to 7 seconds. The value must be an integer between 1 and 60."}},"required":["timeoutInSeconds"]},"StrictnessConfiguration":{"type":"object","properties":{"abuse":{"type":"string","enum":["STRICTEST","STRICTER","BASELINE"],"nullable":true,"description":"Defines how strict or low the threshold is for deeming behavior as abuse: BASELINE is the default if the field is null or omitted, and will cover the most common malicious activities, while STRICTEST is more sensitive to advanced and subtle types of fraud, but can also be triggered by anomalous or uncommon user activity."},"spamAndHoneypot":{"type":"string","enum":["STRICTEST","STRICTER","BASELINE"],"nullable":true,"description":"Defines how strict or low the threshold is for deeming an email address a spam trap or honeypot (meaning that sending emails to these addresses will put your domain on spam blacklists and degrade your sender reputation): BASELINE is the default if the field is null or omitted, and will flag addresses that we have high confidence they fit in this category, while STRICTEST will find more results for newer and less known traps and honeypots."}},"required":["abuse","spamAndHoneypot"]},"EmailRequestConfiguration":{"type":"object","properties":{"smtpCheck":{"nullable":true,"description":"An object that defines the service will contact the SMTP server associated with the email address to gauge its reachability. This process can be time-consuming as it relies on the email provider's response time. If your application is time-sensitive, send this object as null, so we omit contacting the SMTP server; however, results will be less accurate. Nonetheless, our service will still perform analysis and other vital checks on the email address (such as disposability and risk scoring).","allOf":[{"$ref":"#/components/schemas/SmtpCheckConfiguration"}]},"strictness":{"nullable":true,"description":"A configuration that governs how tolerant your application is to abuse/fraud and spam/honeypot email addresses and affects the analysis and scoring that will be performed.","allOf":[{"$ref":"#/components/schemas/StrictnessConfiguration"}]}},"required":["smtpCheck","strictness"]},"EmailInsightsRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"configuration":{"nullable":true,"description":"Options and potential configurations for your request that determine sensitivity levels and the type of analysis you want to perform. Sending this value as null will set all of the underlying properties to their defaults.","allOf":[{"$ref":"#/components/schemas/EmailRequestConfiguration"}]},"email":{"type":"string","nullable":false,"description":"The email address that you want to analyze and obtain insights from."}},"required":["configuration","email"]},"BasicEmailChecks":{"type":"object","properties":{"isFormatValid":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address has a valid structure and fits the email specification. Null if unknown or an error occurred."},"isCommon":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address is from a well known email provider such as gmail, yahoo, hotmail and similar. Null if unknown or an error occurred."},"isGeneric":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address is not personalized or potentially a shared or catch-all email (e.g., admin@example.com, contact@example.com). Null if unknown or an error occurred."},"isDisposable":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address belongs to a temporary or disposable email service; indicating a high likelihood of usage by a fraudster, hacker, scammer, or a person trying to hide their identity. Null if unknown or an error occurred."},"wasRecentlyLeaked":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address appeared in a database leak or data breach recently, and might be compromised (thus making it riskier). Null if unknown or an error occurred."},"isCatchAll":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address is hosted by a server that lets all email addresses through and the email address' status cannot be confirmed. Null if unknown or an error occurred."},"isValidAndReachable":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email server for this address is valid and reachable. Null if unknown or unavailable."},"canReceiveEmail":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address can receive emails. Null if unknown or unavailable."},"isValidAndVerified":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email address is valid, can receive emails, and was verified by our service. Null if unknown or unavailable."}},"required":["isFormatValid","isCommon","isGeneric","isDisposable","wasRecentlyLeaked","isCatchAll","isValidAndReachable","canReceiveEmail","isValidAndVerified"]},"EmailBehavioralTraits":{"type":"object","properties":{"deliverabilityLevel":{"type":"string","enum":["high","medium","low"],"nullable":true,"description":"A string indicating how likely it is that an email sent to this address will reach their inbox."},"emailUsageLevel":{"type":"string","enum":["high","medium","low","none"],"nullable":true,"description":"A string indicating the level of user activity detected for this particular email address, ranging from existing accounts, purchases, online behavior, and other signs of usage. New email addresses will usually have this vale as `none`, while healthy emails will report `high` or `medium`."},"dateFirstSeen":{"format":"date-time","type":"string","nullable":true,"description":"A date string (ISO8601) indicating the time this email was detected by our platform and partner network."},"isFrequentComplainer":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the user constantly unsubscribed from marketing emails and/or issues spam complaints; making it risky to include then in promotional or mass mailing lists."}},"required":["deliverabilityLevel","emailUsageLevel","dateFirstSeen","isFrequentComplainer"]},"EmailLinkedIdentities":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"The name linked to the email account, if available"},"isLikelyCorporateEmail":{"type":"boolean","nullable":true,"description":"A boolean flag indicating whether the email is owned by a company or organization, null if unknown."},"knownNamesAndAliases":{"nullable":false,"description":"A list of previously known names, aliases, and nicknames linked to this user, if known. Please note that these values are best effort and based on immediately available data, for a detailed search, please refer to our Digital Footprint service. This data is unavailable to some plans.","type":"array","items":{"type":"string"}},"knownPhoneNumbers":{"nullable":false,"description":"A list of previously known phone numbers associated to this email address, if any. Please note that these values are best effort and based on immediately available data. This data is unavailable to some plans.","type":"array","items":{"type":"string"}}},"required":["name","isLikelyCorporateEmail","knownNamesAndAliases","knownPhoneNumbers"]},"EmailRiskAnalysis":{"type":"object","properties":{"isValiditySuspicious":{"type":"boolean","nullable":true,"description":"A boolean flag raised when the mail server replies with a temporary error, when the address cannot be verified due to a broken SMTP handshake, or when the email is a catch-all address. When true, the `isFormatValid` flag in the `basicChecks` object might not be reliable; this rarely happens with popular email services and more common for some corporate or business domains. Null if unknown or an error occurred."},"spamTrapLikelihood":{"type":"string","enum":["high","medium","low","none"],"nullable":true,"description":"A string containing the probability of the email address being a spam trap and putting a domain at risk when send emails to it. We recommend to avoid sending emails to addresses with a `high` score."},"usesRiskyTld":{"type":"boolean","nullable":true,"description":"A boolean flag that indicates the email address is hosted on a domain with a TLD (Top-Level Domain, the `.com` in `gooogle.com`), that is commonly used for fraud, phishing, scams, and malicious activity in general."},"hasCommittedRecentAbuse":{"type":"boolean","nullable":true,"description":"A boolean flag that indicates if the email address is linked to recent malicious behavior ranging from chargebacks, fake accounts, and fraudlent behavior."},"isHoneypot":{"type":"boolean","nullable":true,"description":"A boolean flag that indicates if its highly likely that the email address is a honeypot/spam trap and can cause your domain to land in spam blacklists."},"domainTrustLevel":{"type":"string","enum":["trusted","positive","neutral","suspicious","malicious","unknown"],"nullable":true,"description":"A string containing the overall reputation of the domain hosting this email address, considering both malicious behaviour and positive signals."},"fraudScore":{"type":"number","nullable":true,"description":"A numeric score that measures the reputation and recent behavior of an email account across our partner network. Scores equal or above 75 are suspicious (but not necessarily fraudulent)."}},"required":["isValiditySuspicious","spamTrapLikelihood","usesRiskyTld","hasCommittedRecentAbuse","isHoneypot","domainTrustLevel","fraudScore"]},"EmailTechnicalTraits":{"type":"object","properties":{"smtpServerTimedOut":{"type":"boolean","nullable":true,"description":"A flag indicating if the email address' SMTP server failed to respond within the time configuration of your request; null if the configuration omitted querying the remote server. When a time out occurs and the configuration was equal or above the default threshold, the email address is most likely invalid or untrustworthy"},"isDnsValid":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the Domain Name Server is valid and has records for an email service. Null if unknown or unavailable."},"wasDeliverabilityTestRejected":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email server for this address is reachable but returned a temporary mail rejection error. Null if unknown or unavailable."},"hasProperSpfRecord":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email server has configured a proper SPF record. Null if unknown or unavailable."},"hasProperDmarcRecord":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the email server has configured a proper DMARC record. Null if unknown or unavailable."},"mxRecords":{"nullable":false,"description":"The list of MX records for this email's domain server.","type":"array","items":{"type":"string"}},"aRecords":{"nullable":false,"description":"The list of A records for this email's domain server.","type":"array","items":{"type":"string"}},"domainLegitimacyLevel":{"type":"string","enum":["high","medium","low","none"],"nullable":true,"description":"A string indicating the volume of legitimate users interacting with email addresses in this domain, considering domain velocity as well. Consolidated and popular domains (e.g., Gmail, Hotmail) will score highly, while newer emails will report `low` or `none`."},"domainRegistrationDate":{"format":"date-time","type":"string","nullable":true,"description":"A date string (ISO8601) indicating the time the email's domain was registered."}},"required":["smtpServerTimedOut","isDnsValid","wasDeliverabilityTestRejected","hasProperSpfRecord","hasProperDmarcRecord","mxRecords","aRecords","domainLegitimacyLevel","domainRegistrationDate"]},"VeriphOneEmailEnrichmentResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"normalizedEmail":{"type":"string","nullable":true,"description":"A clean version of the email string sent in the request, with masks, aliases and unnecesary characters removed."},"potentiallyCorrectDomain":{"type":"string","nullable":true,"description":"An optional value returned in cases where the address is invalid or the domain is highly similar to a common email service. This helpful to detect user typos and errors such as `gmai.com` instead of `gmail.com`."},"basicChecks":{"nullable":false,"description":"An object containing boolean flags for vital checks performed on the email adddress.","allOf":[{"$ref":"#/components/schemas/BasicEmailChecks"}]},"traits":{"nullable":false,"description":"An object containing information on the user's behavior associated to this email account, along with traits linked to deliverability and friendliness to marketing emails.","allOf":[{"$ref":"#/components/schemas/EmailBehavioralTraits"}]},"linkedIdentities":{"nullable":false,"description":"An object containing information on the user's potential identities, names, and alternative contact information.","allOf":[{"$ref":"#/components/schemas/EmailLinkedIdentities"}]},"riskAnalysis":{"nullable":false,"description":"An object containing critical information on the level of risk you might face when interacting or sending email to this address.","allOf":[{"$ref":"#/components/schemas/EmailRiskAnalysis"}]},"technicalTraits":{"nullable":false,"description":"An object containing technical information on the domain, its DNS records, and configuration.","allOf":[{"$ref":"#/components/schemas/EmailTechnicalTraits"}]}},"required":["normalizedEmail","potentiallyCorrectDomain","basicChecks","traits","linkedIdentities","riskAnalysis","technicalTraits"]},"IpAddressInsightsConfig":{"type":"object","properties":{"reverseGeocodingLanguage":{"type":"string","enum":["en","es","fr","de","ja","pt-BR","ru","zh-CN"],"nullable":false,"default":"en","description":"The language used to reverse geocode the location of the IP address into a human-readable format. Default value is `en`."},"fraudStrictness":{"type":"string","enum":["STRICTEST","STRICTER","STRICT","BASELINE"],"nullable":false,"default":"BASELINE","description":"Defines how strict or low the threshold is for deeming behavior as abuse: BASELINE is the default if the field is omitted, and will cover the most common malicious activities, while STRICTEST is highly sensitive to advanced and subtle types of fraud, but can also be triggered by anomalous or uncommon user activity, leading to some false positives."},"enableForensicChecks":{"type":"boolean","nullable":false,"default":false,"description":"If set to true, the process will perform forensic checks that take longer to process but have a higher fraud detection accuracy. If set to false, the process will be faster, but false negatives may occur. Default value is false."},"allowPublicIpAddresses":{"type":"boolean","nullable":false,"default":true,"description":"If set to true, the process will be more lenient towards IP addresses from corporations, educational institutions, research organizations, or public institutions. Moreover, the process will skip these checks and be more tolerant towards users who rely on public networks. Default value is true."},"relaxedScoring":{"type":"boolean","nullable":false,"default":false,"description":"This configuration will reduce the weight of certain penalties used during scoring and decrease the likelihood of false positives. Default value is false."}},"required":["fraudStrictness","enableForensicChecks","allowPublicIpAddresses","relaxedScoring"]},"IpAddressInsightsRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"ipAddress":{"type":"string","nullable":false,"description":"The IP address to obtain insights from; must be in IPv4 or IPv6 format. Please note that invalid, reserved, private, or local IP addresses (e.g., 127.0.0.1) will return no information."},"userAgent":{"type":"string","nullable":true,"description":"The user agent string associated with the IP address, which we strongly recommend you provide if possible. If sent, we will run additional checks to detect bots and suspicious/invalid browsers. The value is also used to generate the fraud score and can improve scoring accuracy by over 20%."},"userLanguage":{"type":"string","nullable":true,"description":"The user's language header associated with the IP address; if provided, the value will improve the resulting fraud score. Example of expected value: en-US."},"connectionIsMobileApp":{"type":"boolean","nullable":false,"default":false,"description":"If set to true, the process will ignore the user agent string and treat the IP address as a connection from a mobile app, rather than a browser. Use this field carefully, as it can cause unexpected results if the IP address is not coming from a mobile device. Default value is false."},"configuration":{"nullable":false,"description":"A configuration object to override default settings. It is recommended to use this field to fine-tune the insight-generation process. We strongly suggest that if your application is not time-sensitive, you enable forensic checks to obtain the most accurate results.","allOf":[{"$ref":"#/components/schemas/IpAddressInsightsConfig"}]}},"required":["ipAddress"]},"InferredCity":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in the locale of the request (from the configuration object; default is en)."},"confidence":{"type":"number","nullable":true,"maximum":100,"minimum":0,"description":"A value from 0-100 signaling the confidence that the place is correct."}},"required":["geoNameId","localizedName","confidence"]},"InferredContinent":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in the locale of the request (from the configuration object; default is en)."},"code":{"type":"string","description":"2-letter code for the continent the connection is coming from. Possible values: AF (Africa), AN (Antartica), AS (Asia), EU (Europe), NA (North America), OC (Oceania), SA (South America)"}},"required":["geoNameId","localizedName","code"]},"InferredCountry":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in the locale of the request (from the configuration object; default is en)."},"confidence":{"type":"number","nullable":true,"maximum":100,"minimum":0,"description":"A value from 0-100 signaling the confidence that the place is correct."},"isoCode":{"type":"string","description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."}},"required":["geoNameId","localizedName","confidence","isoCode"]},"InferredCountryAssociation":{"type":"object","properties":{"geoNameId":{"type":"number","description":"Place ID from (GeoNames.org)[https://geonames.org]."},"localizedName":{"type":"string","nullable":true,"description":"The place's name in the locale of the request (from the configuration object; default is en)."},"confidence":{"type":"number","nullable":true,"maximum":100,"minimum":0,"description":"A value from 0-100 signaling the confidence that the place is correct."},"isoCode":{"type":"string","description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."},"type":{"type":"string","enum":["military"],"nullable":true,"description":"A string indicating the type of entity that is representing the country, if any. Currently, the only possible value is 'military'."}},"required":["geoNameId","localizedName","confidence","isoCode","type"]},"InferredGeolocation":{"type":"object","properties":{"city":{"nullable":true,"description":"The city the connection is coming from.","allOf":[{"$ref":"#/components/schemas/InferredCity"}]},"continent":{"nullable":true,"description":"The continent the connection is coming from.","allOf":[{"$ref":"#/components/schemas/InferredContinent"}]},"country":{"nullable":true,"description":"The country the connection is coming from.","allOf":[{"$ref":"#/components/schemas/InferredCountry"}]},"accuracyRadiusInKm":{"type":"number","nullable":true,"description":"The accuracy radius in kilometer for the Lat/Lng coordinates of the interpreted geolocation."},"avgIncomeInUSD":{"type":"number","nullable":true,"description":"The known average income in USD of the region the connection is coming from. This value has limited availability."},"latitude":{"type":"number","nullable":true,"description":"The interpreted geolocation's latitude."},"longitude":{"type":"number","nullable":true,"description":"The interpreted geolocation's longitude"},"populationDensity":{"type":"number","nullable":true,"description":"The estimated number of people per square kilometer. This field has limited availability."},"timezone":{"type":"string","nullable":true,"description":"IANA Time Zone for the interpreted geolocation."},"zipCode":{"type":"string","nullable":true,"description":"The approximated zip code of the interpreted geolocation. This value might not be available or complete on all countries."},"zipCodeConfidence":{"type":"number","nullable":true,"maximum":100,"minimum":0,"description":"A value from 0-100 indicating the confidence that the postal code is correct."},"countrySubdivisions":{"description":"An ordered list (descending) of, typically, the state, province, borough, or similar subdivisions of the country where request is coming from. The structure and number of divisions may vary by country.","type":"array","items":{"$ref":"#/components/schemas/InferredCountry"}},"ipCountryAssociation":{"nullable":true,"description":"Used to identify an IP address' linked to another country than where they are geographically located. For instance: IP addresses belonging to embassies or military bases.","allOf":[{"$ref":"#/components/schemas/InferredCountryAssociation"}]},"ipCountryRegistration":{"nullable":true,"description":"The country where the IP address' block was registered by it's ISP. May be different from the user's country.","allOf":[{"$ref":"#/components/schemas/InferredCountry"}]}},"required":["city","continent","country","accuracyRadiusInKm","avgIncomeInUSD","latitude","longitude","populationDensity","timezone","zipCode","zipCodeConfidence","countrySubdivisions","ipCountryAssociation","ipCountryRegistration"]},"AlternativeIpAddressGeolocation":{"type":"object","properties":{"countryIsoCode":{"type":"string","nullable":true,"description":"ISO3166-2 Country Code which can be used to generate the country's name and flag."},"city":{"type":"string","nullable":true,"description":"City of IP address if available or null if unknown."},"regionOrState":{"type":"string","nullable":true,"description":"Region or State of the IP address if available or null if unknown."},"latitude":{"type":"number","nullable":true,"description":"The interpreted geolocation's latitude."},"longitude":{"type":"number","nullable":true,"description":"The interpreted geolocation's longitude"},"timezone":{"type":"string","nullable":true,"description":"IANA Time Zone for the interpreted geolocation."},"zipCode":{"type":"string","nullable":true,"description":"The approximated zip code of the interpreted geolocation. This value is a best guess and it is recommended to take nearby zip codes into consideration when performing analysis. Might be null for some countries and unsupported regions."}},"required":["countryIsoCode","city","regionOrState","latitude","longitude","timezone","zipCode"]},"IpAddressTechnicalTraits":{"type":"object","properties":{"ispName":{"type":"string","nullable":true,"description":"The name of the ISP linked to the IP address."},"organization":{"type":"string","nullable":true,"description":"The organization linked to the IP Address, if known. In some cases, the organization may be ISP or its parent company."},"autonomousSystemNumber":{"type":"number","nullable":true,"description":"The Autonomous System Number associated to this IP address, if any. More info on [ASNs here](https://www.cloudflare.com/learning/network-layer/what-is-an-autonomous-system/)"},"autonomousSystemOrganization":{"type":"string","nullable":true,"description":"The organization linked to the Autonomous System associated to this IP address, if any. More info on [this here](https://www.cloudflare.com/learning/network-layer/what-is-an-autonomous-system/)"},"mobileCountryCode":{"type":"string","nullable":true,"description":"The mobile country code (MCC) linked to the IP address & ISP. More [info here](https://en.wikipedia.org/wiki/Mobile_country_code)"},"mobileNetworkCode":{"type":"string","nullable":true,"description":"The mobile network code (MNC) linked to the IP address & ISP. More [info here](https://en.wikipedia.org/wiki/Mobile_country_code)"},"network":{"type":"string","nullable":true,"description":"The network associated to the IP address."}},"required":["ispName","organization","autonomousSystemNumber","autonomousSystemOrganization","mobileCountryCode","mobileNetworkCode","network"]},"IpAddressUsageTraits":{"type":"object","properties":{"connectionType":{"type":"string","enum":["Cable/DSL","Cellular","Corporate","Dialup","Satellite","Education","Residential","DataCenter"],"nullable":true,"description":"The connection type used by this IP Address."},"domain":{"type":"string","nullable":true,"description":"The domain (e.g., example.com) linked to this IP Address, if any."},"staticIpScore":{"type":"number","nullable":true,"minimum":0,"maximum":99.99,"description":"A number ranging from 0 to 99.99 indicating how static or dynamic the IP address is. The higher, the more likely it is static. Usually, cellular connections score below 1, while Cable/DSL above 30."},"userCountInLast24Hrs":{"type":"number","nullable":true,"description":"The number of estimated users that have shared this IP address in the past 24 hrs. For IPv6, the count is for /64 networks."},"userType":{"type":"string","enum":["business","cafe","cellular","college","consumer_privacy_network","content_delivery_network","dialup","government","hosting","library","military","residential","router","school","search_engine_spider","traveler"],"nullable":true,"description":"The interpreted type of IP address."}},"required":["connectionType","domain","staticIpScore","userCountInLast24Hrs","userType"]},"IpSecurityChecks":{"type":"object","properties":{"externalIpAddress":{"type":"string","nullable":true,"description":"In case the IP address is behind a NAT, the external and reachable IP address. Otherwise, the same IP may be returned."},"isAnonymous":{"type":"boolean","nullable":true,"description":"True if the IP belongs to an anonymous network."},"isAnonymousVpn":{"type":"boolean","nullable":true,"description":"True if the IP is registered by an anonymous VPN vendor."},"isVpn":{"type":"boolean","nullable":true,"description":"True if the IP is linked to a VPN. This can include data center ranges which can become active VPNs at any time"},"isHostingProvider":{"type":"boolean","nullable":true,"description":"True if the IP is linked to a hosting or VPN provider."},"isProxy":{"type":"boolean","nullable":true,"description":"True if the address is a proxy of any type (public, residential, SOCKS, Elite, Anonymous, VPN, Tor, etc.). This value is a summary of the different proxy flag indicators. Null if unknown."},"isPublicProxy":{"type":"boolean","nullable":true,"description":"True if the address is a public proxy."},"isResidentialProxy":{"type":"boolean","nullable":true,"description":"True if the IP belongs to a residential ISP and operated on a suspected anonymizing network."},"isTorNodeOrExit":{"type":"boolean","nullable":true,"description":"True when the address is a Tor node or exit."},"isCrawler":{"type":"boolean","nullable":true,"description":"True when the address is linked to a confirmed crawler from Baidu, Google, Bing, Yahoo, Yandex, Sogou, Exabot, DuckDuckGo, Facebook, Twitter, Pinterest, Naver, UptimeRobot, AppleBot, ArchiveBot, CoccocBot, YisouBot, PetalBot, ByteDance, and MailRU."},"isActiveVpn":{"type":"boolean","nullable":true,"description":"True when the address is linked to a popular or confirmed active VPN provider."},"isSharedConnection":{"type":"boolean","nullable":true,"description":"True when the IP address is linked to a shared connection, such as mobile networks, corporate exit points, and similar. This can also include public networks from places such as libraries, coffee shops, hotels, hospitals and medical centers, or company VPNs. This data point requires a premium plan, null otherwise."},"isDynamicConnection":{"type":"boolean","nullable":true,"description":"True when the IP address is short-lived, volatile, and assigned dynamically. As such, the user will probably be assigned a new one by the provider in the future. This data point requires a premium plan, null otherwise."},"isSecurityScanner":{"type":"boolean","nullable":true,"description":"True when the IP address is associated to a confirmed security scanner or endpoint by a trusted security vendor such as Tenable, Qualys, and similar vendors. This data point requires a premium plan, null otherwise."}},"required":["externalIpAddress","isAnonymous","isAnonymousVpn","isVpn","isHostingProvider","isProxy","isPublicProxy","isResidentialProxy","isTorNodeOrExit","isCrawler","isActiveVpn","isSharedConnection","isDynamicConnection","isSecurityScanner"]},"IpAddressFraudAnalysis":{"type":"object","properties":{"isTrustedNetwork":{"type":"boolean","nullable":true,"description":"True when the IP address identifies an organization or corporate network/access point with historically low malicious behavior and high security protocols. Please consider that this IP may still be compromised by malware or become malicious at any time. This data point requires a premium plan, null otherwise."},"hasReportsOfRecentAbuse":{"type":"boolean","nullable":true,"description":"True when the IP address has been verified to engage in abuse or malicious behavior across our partner networks. Reports can include improper activity from the past few days such as confirmed chargeback, account takeovers, compromised device usage, synthetic/fake registrations, digital impersonation (stolen user data), or bot attacks. It is recommended to use this flag in tandem with other parameters in this object to properly identify bad actors."},"abuseVelocity":{"type":"string","enum":["high","medium","low","none"],"nullable":true,"description":"This value indicates how frequently this IP address is engaging in abuse across our partner networks."},"isFraudulentBot":{"type":"boolean","nullable":true,"description":"True when the IP address has been recently linked to automated (bot), synthetic, or non-human fraud."},"fraudScore":{"type":"number","nullable":true,"description":"The calculated fraud score of the IP address, considering other optional values passed as part of the request like user agent and language. If this value is 75 or above, it is suspicious, but not necessarily fraudulent. Our recommendation is to flag or block interactions with scores greater or equal to 90."},"isFrequentAbuser":{"type":"boolean","nullable":true,"description":"True when the IP address has a consistent history (6 months or more) of malicious behavior. This flag can aid in identifying anonymous addresses which are frequently leverage by fraudsters and bad actors, compared to others that may be briefly compromised and only temporarily active due to malware, or usage in a botnet or residential proxy network. This data point requires a premium plan, null otherwise."},"isEngagedInHighRiskAttacks":{"type":"boolean","nullable":true,"description":"True when the IP address has been associated to phishing, brute forcing, DDoS, credential stuffing & account takeover, scraping, form submission spam, and similar attacks. This data point has a high correlation with anonymous proxies, open proxies, public VPNs, and easily accessible anonymizers. This data point requires a premium plan, null otherwise."}},"required":["isTrustedNetwork","hasReportsOfRecentAbuse","abuseVelocity","isFraudulentBot","fraudScore","isFrequentAbuser","isEngagedInHighRiskAttacks"]},"UserAgentStringAnalysis":{"type":"object","properties":{"isMobile":{"type":"boolean","nullable":true,"description":"True when the user agent is a mobile browser."},"operatingSystem":{"type":"string","nullable":true,"description":"Operating system name and version, null if unknown."},"browser":{"type":"string","nullable":true,"description":"Browser name and version, null if unknown."},"deviceBrand":{"type":"string","nullable":true,"description":"Device brand name, null if unknown."},"deviceModel":{"type":"string","nullable":true,"description":"Device model name, null if unknown."}},"required":["isMobile","operatingSystem","browser","deviceBrand","deviceModel"]},"VeriphOneIpInsightsResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"mostLikelyGeolocation":{"nullable":true,"description":"The interpreted most-likely geolocation of the connection as obtained from the IP address. Null if the primary process fails.","allOf":[{"$ref":"#/components/schemas/InferredGeolocation"}]},"alternativeGeolocation":{"nullable":true,"description":"An additional interpreted geolocation obtained through a different methodology from the IP address. Useful if the first process is unsuccessful or to triangulate the geolocation. Null if the secondary process fails.","allOf":[{"$ref":"#/components/schemas/AlternativeIpAddressGeolocation"}]},"technicalTraits":{"nullable":false,"description":"Technical traits of the IP address.","allOf":[{"$ref":"#/components/schemas/IpAddressTechnicalTraits"}]},"usageTraits":{"nullable":false,"description":"Public and known characteristics of the IP address.","allOf":[{"$ref":"#/components/schemas/IpAddressUsageTraits"}]},"securityChecks":{"nullable":false,"description":"Essential security checks done to understand the type of IP address you are dealing with.","allOf":[{"$ref":"#/components/schemas/IpSecurityChecks"}]},"fraudAnalysis":{"nullable":false,"description":"Fraud-related insights on the IP address and its historical behavior.","allOf":[{"$ref":"#/components/schemas/IpAddressFraudAnalysis"}]},"userAgentStringAnalysis":{"nullable":true,"description":"An object containing insights on the user agent string passed in the API request, the object will be null if the the user agent parameter is not provided or if the connection is configured as mobile.","allOf":[{"$ref":"#/components/schemas/UserAgentStringAnalysis"}]}},"required":["mostLikelyGeolocation","alternativeGeolocation","technicalTraits","usageTraits","securityChecks","fraudAnalysis","userAgentStringAnalysis"]},"GeolocationInsightsRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"latitude":{"type":"number","example":19.4326,"description":"Latitude coordinate between -90 and 90","minimum":-90,"maximum":90},"longitude":{"type":"number","example":-99.1332,"description":"Longitude coordinate between -180 and 180","minimum":-180,"maximum":180},"accuracyRadiusInMeters":{"type":"number","example":1000,"default":0,"description":"Accuracy radius in meters (max 50000). If not provided, defaults to 0. Note: High-precision security signals (e.g., isInsidePrison) are only computed when accuracy <= 500 meters; otherwise those fields will be null to avoid false positives.","minimum":0,"maximum":50000},"financialSearchRadiusInMeters":{"type":"number","example":1500,"default":3000,"description":"Custom radius in meters for the financial infrastructure search (defaults to 3000 when omitted).","minimum":100,"maximum":10000},"language":{"type":"string","example":"es","default":"en","description":"IETF language code used to localize the reverse geocoded address (e.g., zh-CN, fr, es-419).","enum":["af","sq","am","ar","hy","az","eu","be","bn","bs","bg","my","ca","zh","zh-CN","zh-HK","zh-TW","hr","cs","da","nl","en","en-AU","en-GB","et","fa","fi","fil","fr","fr-CA","gl","ka","de","el","gu","iw","hi","hu","is","id","it","ja","kn","kk","km","ko","ky","lo","lv","lt","mk","ms","ml","mr","mn","ne","no","pl","pt","pt-BR","pt-PT","pa","ro","ru","sr","sr-Latn","si","sk","sl","es","es-419","sw","sv","ta","te","th","tr","uk","ur","uz","vi","zu"]}},"required":["latitude","longitude"]},"GeolocationAddress":{"type":"object","properties":{"country":{"type":"string","nullable":true,"description":"Name of the country obtained by reverse geocoding. Null when the service cannot determine a country (e.g., open ocean).","example":"México"},"countryIsoCode":{"type":"string","nullable":true,"description":"Two-letter ISO 3166-1 alpha-2 code obtained via reverse geocoding. Null when unavailable or non-applicable.","example":"MX"},"firstLevelDivision":{"type":"string","nullable":true,"description":"First-level territorial division such as state or province.","example":"Ciudad de México"},"secondLevelDivision":{"type":"string","nullable":true,"description":"Second-level division such as municipality or major locality.","example":"Cuauhtémoc"},"locality":{"type":"string","nullable":true,"description":"Neighborhood or locality label.","example":"Centro Histórico"},"streetLine":{"type":"string","nullable":true,"description":"Street, avenue or road name.","example":"Calzada de Tlalpan"},"streetNumber":{"type":"string","nullable":true,"description":"Building, exterior or street number.","example":"123"}},"required":["country","countryIsoCode","firstLevelDivision","secondLevelDivision","locality","streetLine","streetNumber"]},"HighRiskLocations":{"type":"object","properties":{"isInsidePrison":{"type":"boolean","nullable":true,"description":"Whether the location is inside a prison facility. Computed only when request accuracy <= 100 meters; otherwise null."},"nearnessToPrison":{"type":"number","nullable":true,"description":"Distance to nearest prison facility in meters. When an accuracy radius is provided, this distance is computed based on the center (the lat/lng coordinates). Please note that in some regions, prisons can be located in hihgly populated areas such as municipal centers and cities, so the distance to the nearest prison should be used in a context-aware manner."}},"required":["isInsidePrison","nearnessToPrison"]},"CriminalIncidence":{"type":"object","properties":{"relativeToCountry":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Indicates the relative level of criminal incidence for a municipality compared to all municipalities in the country during the same period (typically in a year). This value is computed using a min-max normalization across all municipalities in the country. \n- A value of 0 means that the municipality has the lowest criminal incidence among all municipalities nationwide. \n- A value of 100 indicates the highest criminal incidence in the entire country. \n- Intermediate values (e.g., 20, 55, 80) represent positions along the national scale, not percentages of total crimes."},"relativeToState":{"type":"number","minimum":0,"maximum":100,"nullable":true,"description":"Indicates the relative level of criminal incidence for a given municipality compared to all other municipalities within the same state. This value is calculated using a min-max normalization across all municipalities in that state for the corresponding year. \n- A value of 0 means that the municipality has the lowest criminal incidence in its state. \n- A value of 100 indicates the highest criminal incidence in the state. \n- Intermediate values (e.g., 25, 60, etc.) represent positions between the lowest and highest levels, not percentages of total crimes."}},"required":["relativeToCountry","relativeToState"]},"SecurityStats":{"type":"object","properties":{"highRiskLocations":{"nullable":true,"description":"Contains fields indicating whether the input location is inside or near a known high-risk area. Only available for Mexico.","allOf":[{"$ref":"#/components/schemas/HighRiskLocations"}]},"criminalIncidence":{"nullable":true,"description":"Provides relative crime incidence metrics based on officially reported data. Only available for Mexico.","allOf":[{"$ref":"#/components/schemas/CriminalIncidence"}]}},"required":["highRiskLocations","criminalIncidence"]},"QualityOfLifeStats":{"type":"object","properties":{"costOfLiving":{"type":"number","nullable":true,"minimum":0,"description":"Estimated cost-of-living for the state-level region, based on official data of price indexes. Expressed in the monthy amount needed to cover basic expenses (e.g. food, housing, transportation, etc.) in local currency (e.g. MXN for Mexico)."},"socialLag":{"type":"number","minimum":0,"nullable":true,"description":"Social lag index of the location's locality (i.e., neighborhood, town, or the level below municipality) as published by official sources. Reflects the degree of social backwardness in education, health, and housing access. Scaled so that lower values represent better conditions (less lag) and higher values represent greater deprivation"},"humanDevelopmentIndex":{"type":"number","nullable":true,"minimum":0,"maximum":1,"description":"Human Development Index (HDI) value for the location's municipality as sourced from the United Nations Development Programme (UNDP). Measures combined performance in education, health, and income, ranging from 0 (lowest) to 1 (highest)."},"marginalizationIndex":{"type":"number","nullable":true,"minimum":0,"maximum":100,"description":"Marginalization index for the location's municipality provided by government datasets. It captures the structural social and economic exclusion level. Typically scaled from 0 to 100, where 100 indicates the highest marginalization. Used to assess long-term inequality and access to basic services."},"medianIncome":{"type":"number","nullable":true,"description":"Represents the middle point of the income distribution for a person at a state level. Expressed in local currency (e.g. MXN for Mexico) for monthly income."},"isRuralArea":{"type":"boolean","nullable":true,"description":"Determines whether the location is classified as a rural area, false if urban. Null if the location is outside coverage or a remote location (e.g., open sea or uninhabited places)."}},"required":["costOfLiving","socialLag","humanDevelopmentIndex","marginalizationIndex","medianIncome","isRuralArea"]},"FinancialInfrastructure":{"type":"object","properties":{"numOfAtms":{"type":"number","minimum":0,"description":"Total number of automated teller machines (ATMs) located within the provided radius around the location. Indicates accessibility to cash withdrawal and deposit services. Null if unknown or unavailable.","nullable":true},"numOfBankBranches":{"type":"number","minimum":0,"description":"Total number of bank branches or retail financial services located within the same area. Represents proximity to formal financial institutions and in-person banking services. Null if unknown or unavailable.","nullable":true}},"required":["numOfAtms","numOfBankBranches"]},"RelevantLocations":{"type":"object","properties":{"financialInfrastructure":{"description":"Provides aggregated data on banking and cash-access points near the input location. Values are typically computed by counting institutions or service points within a defined search radius by default of 3000 meters","nullable":true,"allOf":[{"$ref":"#/components/schemas/FinancialInfrastructure"}]}},"required":["financialInfrastructure"]},"GeolocationStats":{"type":"object","properties":{"security":{"description":"Represents geospatial security insights for the specified coordinates. Currently only available for Mexico, if the geolocation is outside coverage, null is returned.","nullable":true,"allOf":[{"$ref":"#/components/schemas/SecurityStats"}]},"qualityOfLife":{"description":"This object aggregates socioeconomic and human-development indicators that describe living conditions in the area surrounding the input location. Only available for Mexico, null if location is outside coverage.","nullable":true,"allOf":[{"$ref":"#/components/schemas/QualityOfLifeStats"}]},"relevantLocations":{"description":"Contains information about notable or economically relevant infrastructure near the given coordinates. This section helps identify the economical development level of the surrounding area. Currently, it focuses on financial infrastructure.","nullable":true,"allOf":[{"$ref":"#/components/schemas/RelevantLocations"}]}},"required":["security","qualityOfLife","relevantLocations"]},"VeriphOneGeolocationInsights":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"address":{"description":"An approximate address obtained from reverse geocoding; null when the service cannot reliably determine an address. Notes: 1) The address is localized based on the language parameter. 2) The address is not always available, as it depends on the accuracy of the input coordinates, 3) Some fields might be null depending on the accuracy of the input coordinates and the location/country.","nullable":true,"allOf":[{"$ref":"#/components/schemas/GeolocationAddress"}]},"stats":{"description":"Geostatistical information about the provided location; this object includes insights on security, quality of life, and relevant locations (e.g., financial infrastructure). This information can be used as signals of inability of a user to repay a loan (e.g., high crime rate, low development index, lack of financial infrastructure), or the likelihood of fraud (e.g., high crime rate, location inside or near a prison, low economic development and employment opportunities).","allOf":[{"$ref":"#/components/schemas/GeolocationStats"}]}},"required":["address","stats"]},"ProofOfAddressValidationRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"documentB64":{"type":"string","nullable":false,"description":"A PDF document or JPG image of the Proof of Address to validate encoded as a Base64 string. For better performance and reduced response time, use JPG images and keep the file size as small as possible without compromising readability (please keep in mind that that if the image is too small or pixelated, the OCR will fail and the service can have unintended results). Usually a reasonable file size is within 1 to 3 MBs."},"timeoutInSeconds":{"type":"number","minimum":1,"maximum":3600,"nullable":false,"description":"An optional value that governs how long the service will wait for an attestation response from the PoA's issuer. If the third-party is under heavy load or facing availability issues, requests can hang or be delayed. If not provided, the service will default to 60 seconds. The value must be an integer between 1 and 3600."}},"required":["documentB64"]},"GenericAddress":{"type":"object","properties":{"addressLine1":{"type":"string","nullable":true,"description":"A string containing the domicile's street name, external number and int. number."},"references":{"type":"string","nullable":true,"description":"A string describing nearby streets or places of interest linked to the location."},"city":{"type":"string","nullable":true,"description":"The address' city or municipality."},"zipCode":{"type":"string","nullable":true,"description":"The address' postal code."},"neighborhood":{"type":"string","nullable":true,"description":"The domicile's neighborhood (i.e. 'colonia' in Mexico)."},"state":{"type":"string","nullable":true,"description":"The state in which the address is located, as an abbreviation, e.g., CDMX."}},"required":["addressLine1","references","city","zipCode","neighborhood","state"]},"CfeServiceDetails":{"type":"object","properties":{"serviceNumber":{"type":"string","nullable":true,"description":"Service number: the unique contract ID linked to the service"},"rmu":{"type":"string","nullable":true,"description":"The RMU (Registro Móvil de Usuario) identifier which is used to uniquely identify a CFE customer."},"barCode":{"type":"string","nullable":true,"description":"A string that includes the contents of the barcode found on the bill."},"meterId":{"type":"string","nullable":true,"description":"Consumption meter identifier (número de medidor)."},"priceType":{"type":"string","nullable":true,"description":"Price type applied to this service (tarifa)."},"multiplier":{"type":"string","nullable":true,"description":"Multiplier applied to this service (multiplicador)."}},"required":["serviceNumber","rmu","barCode","meterId","priceType","multiplier"]},"TelmexServiceDetails":{"type":"object","properties":{"barCode":{"type":"string","nullable":true,"description":"A string that includes the contents of the barcode found on the bill."},"invoiceNumber":{"type":"string","nullable":true,"description":"Invoice number."},"numericalCode":{"type":"string","nullable":true,"description":"Bill ID number."},"phoneNumber":{"type":"string","nullable":true,"description":"The associated phone number."}},"required":["barCode","invoiceNumber","numericalCode","phoneNumber"]},"TelcelServiceDetails":{"type":"object","properties":{"barCode":{"type":"string","nullable":true,"description":"A string that includes the contents of the barcode found on the bill."},"accountId":{"type":"string","nullable":true,"description":"The account's or contract's unique id."},"phoneNumber":{"type":"string","nullable":true,"description":"The associated phone number."},"numericalCode":{"type":"string","nullable":true,"description":"Bill ID number."},"mobilePlanName":{"type":"string","nullable":true,"description":"A label describing the mobile plan that the client is paying for."},"mobilePlanMonthlyCost":{"type":"string","nullable":true,"description":"The mobile plan's monthly cost."}},"required":["barCode","accountId","phoneNumber","numericalCode","mobilePlanName","mobilePlanMonthlyCost"]},"MegacableServiceDetails":{"type":"object","properties":{"barCode":{"type":"string","nullable":true,"description":"A string that includes the contents of the barcode found on the bill."},"phoneNumber":{"type":"string","nullable":true,"description":"The associated phone number."},"previousBalance":{"type":"string","nullable":true,"description":"An outstanding balance from past bills."},"accountId":{"type":"string","nullable":true,"description":"The account's or contract's unique id."},"numericalCode":{"type":"string","nullable":true,"description":"Bill ID number."}},"required":["barCode","phoneNumber","previousBalance","accountId","numericalCode"]},"SkyServiceDetails":{"type":"object","properties":{"accountId":{"type":"string","nullable":true,"description":"The account's or contract's unique id."},"previousBalance":{"type":"string","nullable":true,"description":"An outstanding balance from past bills."},"phoneNumber":{"type":"string","nullable":true,"description":"The associated phone number."},"invoiceNumber":{"type":"string","nullable":true,"description":"Invoice number."}},"required":["accountId","previousBalance","phoneNumber","invoiceNumber"]},"IzziServiceDetails":{"type":"object","properties":{"phoneNumber":{"type":"string","nullable":true,"description":"The associated phone number."},"previousBalance":{"type":"string","nullable":true,"description":"An outstanding balance from past bills."},"accountId":{"type":"string","nullable":true,"description":"The account's or contract's unique id."},"numericalCode":{"type":"string","nullable":true,"description":"Bill ID number."}},"required":["phoneNumber","previousBalance","accountId","numericalCode"]},"OcrServiceDetails":{"type":"object","properties":{"cfeServiceDetails":{"nullable":true,"description":"An object containing additional details from a CFE bill. Null if the document is of a different type.","allOf":[{"$ref":"#/components/schemas/CfeServiceDetails"}]},"telmexServiceDetails":{"nullable":true,"description":"An object containing additional details from a Telmex bill. Null if the document is of a different type.","allOf":[{"$ref":"#/components/schemas/TelmexServiceDetails"}]},"telcelServiceDetails":{"nullable":true,"description":"An object containing additional details from a Telcel bill. Null if the document is of a different type.","allOf":[{"$ref":"#/components/schemas/TelcelServiceDetails"}]},"megacableServiceDetails":{"nullable":true,"description":"An object containing additional details from a Megacable bill. Null if the document is of a different type.","allOf":[{"$ref":"#/components/schemas/MegacableServiceDetails"}]},"skyServiceDetails":{"nullable":true,"description":"An object containing additional details from a Sky bill. Null if the document is of a different type.","allOf":[{"$ref":"#/components/schemas/SkyServiceDetails"}]},"izziServiceDetails":{"nullable":true,"description":"An object containing additional details from a Izzi bill. Null if the document is of a different type.","allOf":[{"$ref":"#/components/schemas/IzziServiceDetails"}]}},"required":["cfeServiceDetails","telmexServiceDetails","telcelServiceDetails","megacableServiceDetails","skyServiceDetails","izziServiceDetails"]},"OcrExtractionResult":{"type":"object","properties":{"issuer":{"type":"string","enum":["CFE","Telmex","Telcel","Megacable","Sky","Izzi"],"nullable":true,"description":"The document's issuer based on OCR results. Null if unknown or unsupported."},"clientName":{"type":"string","nullable":true,"description":"Client name as parsed by OCR."},"address":{"description":"Address data extracted via OCR.","nullable":true,"allOf":[{"$ref":"#/components/schemas/GenericAddress"}]},"serviceDetails":{"nullable":true,"description":"OCR-read issuer-specific fields.","allOf":[{"$ref":"#/components/schemas/OcrServiceDetails"}]},"issuanceDate":{"type":"string","nullable":true,"description":"Issue date of the bill, if available."},"paymentExpectedBy":{"type":"string","nullable":true,"description":"A date describing the deadline to pay this bill, if available."},"paymentOverdueDate":{"type":"string","nullable":true,"description":"A threshold date after which the account becomes overdue or service will be interrupted if left unpaid, if available."},"billingPeriod":{"type":"string","nullable":true,"description":"An object containing the billed period details."},"amountDue":{"type":"string","nullable":true,"description":"Amount due for the billing cycle."}},"required":["issuer","clientName","address","serviceDetails","issuanceDate","paymentExpectedBy","paymentOverdueDate","billingPeriod","amountDue"]},"CoherenceCheck":{"type":"object","properties":{"title":{"type":"string","enum":["ServiceNumber","Date","NumericalId","Rmu","PricingType","AmountDue","AccountId","IssuanceDate","PaymentExpectedBy"],"nullable":false,"description":"A label that indicates the type of coherence check or the name of the field that was validated."},"successful":{"type":"boolean","nullable":true,"description":"A boolean flag indicating if the coherence check test passed. The value can null if the result is inconclusive or if the test failed."}},"required":["title","successful"]},"ValidityCheckItem":{"type":"object","properties":{"olderThan60Days":{"type":"boolean","nullable":false,"description":"Measures if the date is greater than 60 days from today (time of the request)."},"olderThan90Days":{"type":"boolean","nullable":false,"description":"Measures if the date is greater than 90 days from today (time of the request)."},"olderThan120Days":{"type":"boolean","nullable":false,"description":"Measures if the date is greater than 120 days from today (time of the request)."}},"required":["olderThan60Days","olderThan90Days","olderThan120Days"]},"ValidityChecks":{"type":"object","properties":{"issuanceDate":{"nullable":true,"description":"And object that cross checks the validity (in terms of recency) of the document against its issuanceDate. Null if the date was not retrieved from the OCR process.","allOf":[{"$ref":"#/components/schemas/ValidityCheckItem"}]},"paymentExpectedBy":{"nullable":true,"description":"And object that cross checks the validity (in terms of recency) of the document against its paymentExpectedBy field. Null if the date was not retrieved from the OCR process.","allOf":[{"$ref":"#/components/schemas/ValidityCheckItem"}]},"paymentOverdueDate":{"nullable":true,"description":"And object that cross checks the validity (in terms of recency) of the document against its paymentOverdueDate. Null if the date was not retrieved from the OCR process.","allOf":[{"$ref":"#/components/schemas/ValidityCheckItem"}]},"billingPeriodStartDate":{"nullable":true,"description":"And object that cross checks the validity (in terms of recency) of the document against its billingPeriodStartDate. Null if the date was not retrieved from the OCR process.","allOf":[{"$ref":"#/components/schemas/ValidityCheckItem"}]},"billingPeriodEndDate":{"nullable":true,"description":"And object that cross checks the validity (in terms of recency) of the document against its billingPeriodEndDate. Null if the date was not retrieved from the OCR process.","allOf":[{"$ref":"#/components/schemas/ValidityCheckItem"}]}},"required":["issuanceDate","paymentExpectedBy","paymentOverdueDate","billingPeriodStartDate","billingPeriodEndDate"]},"TaxValidationResult":{"type":"object","properties":{"taxableBase":{"type":"string","nullable":true,"description":"Taxable base amount for the concept."},"taxAmount":{"type":"string","nullable":true,"description":"Tax amount applied to the concept."},"taxCode":{"type":"string","nullable":true,"description":"Tax code identifier (e.g., IVA)."},"factorType":{"type":"string","nullable":true,"description":"Factor type for the tax (e.g., Tasa, Cuota)."}},"required":["taxableBase","taxAmount","taxCode","factorType"]},"ItemValidationResult":{"type":"object","properties":{"quantity":{"type":"string","nullable":true,"description":"Quantity of the billed concept."},"serviceCode":{"type":"string","nullable":true,"description":"Service/product code (ClaveProdServ)."},"unitCode":{"type":"string","nullable":true,"description":"Unit Code."},"description":{"type":"string","nullable":true,"description":"Description of the concept."},"amount":{"type":"string","nullable":true,"description":"Amount for the concept."},"taxConceptId":{"type":"string","nullable":true,"description":"Tax concept identifier (ObjetoImp)."},"unitPrice":{"type":"string","nullable":true,"description":"Unit price of the concept."},"taxes":{"description":"Array of taxes applied to this concept.","type":"array","items":{"$ref":"#/components/schemas/TaxValidationResult"}}},"required":["quantity","serviceCode","unitCode","description","amount","taxConceptId","unitPrice","taxes"]},"CfdiInvoiceIssuer":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Issuer legal name."},"taxRegimeCode":{"type":"string","nullable":true,"description":"Issuer tax regime code."},"rfc":{"type":"string","nullable":true,"description":"Issuer RFC (Tax id)"}},"required":["name","taxRegimeCode","rfc"]},"CfdiInvoiceTaxes":{"type":"object","properties":{"totalTransferTaxes":{"type":"string","nullable":true,"description":"Total transfered taxes (impuestos trasladados)."}},"required":["totalTransferTaxes"]},"CfdiInvoiceRecipient":{"type":"object","properties":{"recipientTaxAddress":{"type":"string","nullable":true,"description":"Recipient tax address (postal code)."},"name":{"type":"string","nullable":true,"description":"Recipient name."},"recipientTaxRegime":{"type":"string","nullable":true,"description":"Recipient tax regime."},"rfc":{"type":"string","nullable":true,"description":"Recipient RFC (Tax Id)."},"cfdiUsage":{"type":"string","nullable":true,"description":"Declared CFDI usage (UsoCFDI)."}},"required":["recipientTaxAddress","name","recipientTaxRegime","rfc","cfdiUsage"]},"IssuerInvoiceData":{"type":"object","properties":{"date":{"type":"string","nullable":true,"description":"The date the CFDI was issued."},"invoiceNumber":{"type":"string","nullable":true,"description":"Folio / unique invoice identificator."},"paymentMethodCode":{"type":"string","nullable":true,"description":"Payment method code."},"items":{"description":"Array of line items (conceptos).","type":"array","items":{"$ref":"#/components/schemas/ItemValidationResult"}},"issuer":{"description":"CFDI issuer information.","allOf":[{"$ref":"#/components/schemas/CfdiInvoiceIssuer"}]},"taxes":{"description":"An object containing a detailed description of tax totals.","allOf":[{"$ref":"#/components/schemas/CfdiInvoiceTaxes"}]},"placeOfIssuance":{"type":"string","nullable":true,"description":"Place of issuance."},"paymentMethod":{"type":"string","nullable":true,"description":"Payment method (método de pago), e.g., PPD."},"currency":{"type":"string","nullable":true,"description":"Currency, e.g., MXN."},"recipient":{"description":"Recipient information.","allOf":[{"$ref":"#/components/schemas/CfdiInvoiceRecipient"}]},"series":{"type":"string","nullable":true,"description":"Series identifier."},"subTotal":{"type":"string","nullable":true,"description":"Subtotal before taxes."},"invoiceType":{"type":"string","nullable":true,"description":"CFDI type, e.g., I (Ingreso)."},"total":{"type":"string","nullable":true,"description":"Total including taxes."},"version":{"type":"string","nullable":true,"description":"CFDI version (e.g., 4.0)."}},"required":["date","invoiceNumber","paymentMethodCode","items","issuer","taxes","placeOfIssuance","paymentMethod","currency","recipient","series","subTotal","invoiceType","total","version"]},"IssuerCustomerDetails":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Customer full name as retrieved from the issuer's database."},"address":{"description":"Customer address as as retrieved from the issuer's database.","nullable":true,"allOf":[{"$ref":"#/components/schemas/GenericAddress"}]}},"required":["name","address"]},"IssuerCustomerData":{"type":"object","properties":{"customer":{"description":"Customer information (name and address).","nullable":true,"allOf":[{"$ref":"#/components/schemas/IssuerCustomerDetails"}]},"cfeServiceData":{"description":"An object describing the CFE-specific details of the client and its service.","nullable":true,"allOf":[{"$ref":"#/components/schemas/IssuerCustomerDetails"}]}},"required":["customer","cfeServiceData"]},"IssuerProvidedData":{"type":"object","properties":{"invoiceData":{"description":"Invoice data extracted from the invoice CFDI (header, issuer, recipient, items, and amounts).","nullable":true,"allOf":[{"$ref":"#/components/schemas/IssuerInvoiceData"}]},"customerData":{"description":"Data that the issuer has in its databases about the customer.","nullable":true,"allOf":[{"$ref":"#/components/schemas/IssuerCustomerData"}]}},"required":["invoiceData","customerData"]},"DocumentFieldAnomaly":{"type":"object","properties":{"label":{"type":"string","enum":["name","addressLine1","references","neighborhood","city","zipCode","state"],"nullable":false,"description":"A label that indicates the type of field where an anomaly was found."},"valueFromOcr":{"type":"string","nullable":true,"description":"A string that contains the value that was extracted from the document via OCR."},"valueFromIssuingSource":{"type":"string","nullable":true,"description":"A string that contains the value that was obtained via attestation from the issuer."},"distinctness":{"type":"number","maximum":1,"minimum":0,"nullable":false,"description":"A number ranging from 0 (lowest score; same string) to 1 (highest score; completely distinct) that measures how different are the two values."},"weight":{"type":"number","nullable":false,"description":"The weight of the anomaly for the purpose of generating a document-wide score."}},"required":["label","valueFromOcr","valueFromIssuingSource","distinctness","weight"]},"DocumentAnalysisAnomaly":{"type":"object","properties":{"type":{"type":"string","enum":["FullNameComparison","AddressSegment","Attestation","ServiceNumber","Date","NumericalId","Rmu","PricingType","AmountDue"],"nullable":false,"description":"A label that indicates the type of anomaly found."},"description":{"type":"string","nullable":false,"description":"A human-friendly description of the anomaly."},"score":{"type":"number","maximum":1,"minimum":0,"nullable":false,"description":"The scoring given to this anomaly, in the case of address segments and similar fields, this score is generated by the multiplication of its weight and distinctness"},"fieldDetails":{"nullable":true,"description":"An object containing a detailed description of how the anomaly was scored and generated.","allOf":[{"$ref":"#/components/schemas/DocumentFieldAnomaly"}]}},"required":["type","description","score","fieldDetails"]},"PoAValidationResult":{"type":"object","properties":{"score":{"type":"number","maximum":100,"minimum":0,"nullable":false,"description":"A number ranging from 0 (lowest score; most likely a forgery or invalid document) to 100 (highest score; document has no clear signs of alteration) that measures the probability of a document being authentic. Please note that sometimes OCR errors can occur or the issuer might misprint or have data inconsistencies that lead to a lower score; which is why, we provide the anomaliesFound array that shows you how this score was generated. Finally, consider that this score cannot go below zero, even if the anomalies exceed this value."},"resultCode":{"type":"string","enum":["LIKELY_AUTHENTIC","AUTHENTICITY_INCONCLUSIVE","LIKELY_NOT_AUTHENTIC"],"nullable":false,"description":"A human-friendly label that categorizes scores into three ranges LIKELY_AUTHENTIC (score >= 90), AUTHENTICITY_INCONCLUSIVE (score >= 75), LIKELY_NOT_AUTHENTIC (score < 75)."},"anomaliesFound":{"description":"An array of failed validations that occurred during the attestation and analysis of the provided document, including the elements that were taken into consideration for the scores (e.g., weights).","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/DocumentAnalysisAnomaly"}}},"required":["score","resultCode","anomaliesFound"]},"ProofOfAddressValidationResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"ocrExtractedData":{"nullable":false,"description":"An object containing the data extracted from the document via OCR.","allOf":[{"$ref":"#/components/schemas/OcrExtractionResult"}]},"basicCoherenceChecks":{"nullable":false,"description":"A list of simple checks performed on the proof-of-address to analyze and detect issues in its contents. These are performed after the OCR process is completed and are performed entirely on the document's contents, not through attestation.","type":"array","items":{"$ref":"#/components/schemas/CoherenceCheck"}},"validityChecks":{"nullable":false,"description":"An object comparing the different dates in the document against the time of the request to determine how recent or outdated the document is.","allOf":[{"$ref":"#/components/schemas/ValidityChecks"}]},"issuerProvidedData":{"nullable":true,"description":"If attestation is supported or the document type, this object includes information provided by issuer during the validation process. May be null if not retrievable or supported. Supported document types: Comisión Federal de Electricidad (Mexico).","allOf":[{"$ref":"#/components/schemas/IssuerProvidedData"}]},"attestationResultCode":{"type":"string","enum":["ATTESTATION_UNSUPPORTED","ATTESTATION_UNAVAILABLE","ATTESTATION_TIMEOUT","ATTESTATION_FAILED","ATTESTATION_DONE","ATTESTATION_IMPEDED_BY_DOCUMENT_QUALITY"],"nullable":false,"description":"A code indicating if attestation was performed on the document and whether an analysis beyong basic coherence checks was done."},"validationAnalysis":{"nullable":true,"description":"An object contain the result of the validation (from attestation, if supported for this document type) and the document's integrity score.","allOf":[{"$ref":"#/components/schemas/PoAValidationResult"}]}},"required":["ocrExtractedData","basicCoherenceChecks","validityChecks","issuerProvidedData","attestationResultCode","validationAnalysis"]},"IdempotentProofOfAddressOcrRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"A string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"documentB64":{"type":"string","nullable":false,"description":"A PDF document or JPG image of the Proof of Address to validate encoded as a Base64 string. For better performance and reduced response time, use JPG images and keep the file size as small as possible without compromising readability (please keep in mind that that if the image is too small or pixelated, the OCR will fail and the service can have unintended results). Usually a reasonable file size is within 1 to 3 MBs."}},"required":["requestUuid","documentB64"]},"ProofOfAddressOcrResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"ocrExtractedData":{"nullable":false,"description":"An object containing the data extracted from the document via OCR.","allOf":[{"$ref":"#/components/schemas/OcrExtractionResult"}]},"basicCoherenceChecks":{"nullable":false,"description":"A list of simple checks performed on the proof-of-address to analyze and detect issues in its contents. These are performed after the OCR process is completed and are performed entirely on the document's contents, not through attestation.","type":"array","items":{"$ref":"#/components/schemas/CoherenceCheck"}},"validityChecks":{"nullable":false,"description":"An object comparing the different dates in the document against the time of the request to determine how recent or outdated the document is.","allOf":[{"$ref":"#/components/schemas/ValidityChecks"}]}},"required":["ocrExtractedData","basicCoherenceChecks","validityChecks"]},"ProofOfAddressAttestationRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"timeoutInSeconds":{"type":"number","minimum":1,"maximum":3600,"nullable":false,"description":"An optional value that governs how long the service will wait for an attestation response from the PoA's issuer. If the third-party is under heavy load or facing availability issues, requests can hang or be delayed. If not provided, the service will default to 60 seconds. The value must be an integer between 1 and 3600."},"ocrRequestUuid":{"type":"string","nullable":false,"description":"A string containing the UUID provided by your application to the OCR endpoint. The attestation process will be executed against the information extracted by that service. This service is idempotent, and repeated calls with the same `ocrRequestUuid` will return the same result (unless the result is not ready)."}},"required":["ocrRequestUuid"]},"ProofOfAddressAttestationResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"issuerProvidedData":{"nullable":true,"description":"If attestation is supported or the document type, this object includes information provided by issuer during the validation process. May be null if not retrievable or supported. Supported document types: Comisión Federal de Electricidad (Mexico).","allOf":[{"$ref":"#/components/schemas/IssuerProvidedData"}]},"attestationResultCode":{"type":"string","enum":["ATTESTATION_UNSUPPORTED","ATTESTATION_UNAVAILABLE","ATTESTATION_TIMEOUT","ATTESTATION_FAILED","ATTESTATION_DONE","ATTESTATION_IMPEDED_BY_DOCUMENT_QUALITY"],"nullable":false,"description":"A code indicating if attestation was performed on the document and whether an analysis beyong basic coherence checks was done."},"validationAnalysis":{"nullable":true,"description":"An object contain the result of the validation (from attestation, if supported for this document type) and the document's integrity score.","allOf":[{"$ref":"#/components/schemas/PoAValidationResult"}]}},"required":["issuerProvidedData","attestationResultCode","validationAnalysis"]},"TaxIdSearchParams":{"type":"object","properties":{"country":{"type":"string","enum":["MX"],"nullable":false,"description":"The ISO3166-2 country code of where to make the search/validation."},"nationalId":{"type":"string","nullable":true,"description":"The national ID or equivalent used to uniquely identify a person in a country (e.g., CURP in Mexico). Can be null if another identity element is provided."},"taxId":{"type":"string","nullable":true,"description":"The tax ID or equivalent used to uniquely identify a person for taxing purposes in a country (e.g., RFC in Mexico). Can be null if a national ID is provided."},"listsToSearch":{"type":"array","nullable":true,"description":"The lists and blacklists to search for. If empty, null or undefined, list search will be skipped.","items":{"type":"string","enum":["SAT_Article69","SAT_Article69-B"]}}},"required":["country","nationalId","taxId"]},"TaxIdValidationRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"searchParams":{"nullable":false,"description":"The search parameters for the tax ID validation request.","allOf":[{"$ref":"#/components/schemas/TaxIdSearchParams"}]}},"required":["searchParams"]},"MexicoTaxListArticle69Match":{"type":"object","properties":{"listName":{"type":"string","enum":["CancelledCredit","PenaltyReduction","BankrupcyRelief","CreditFeeReduction","CreditCondonationByDecree","CreditCondonation","TaxReturnOnInvestment","TaxCreditDueAndPayable","TaxCreditUnappealable","NotFoundAtFiscalAddress","FinalJudicialSentences","DigitalCertificateInvalidated","OmittingGovernmentBodies","Other"],"nullable":false,"description":"The name of the list where the tax ID was found."},"state":{"type":"string","nullable":true,"description":"The geographical state associated with the tax ID; if available."},"dateFirstPublished":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was first published in ISO 8601 format. Null if unknown."},"yearOfAppearance":{"type":"string","nullable":true,"description":"Year of appearance of the tax ID on the list (e.g., 2022). Null if unknown."},"reasonOrCause":{"type":"string","nullable":true,"description":"The reason or cause the tax ID appears on the list; if available."},"riskLevel":{"type":"string","enum":["Unknown","Contextual","None","Low","Medium","High"],"nullable":true,"description":"The risk level of the tax ID appearance on the list; if measurable. A high risk will mark the tax ID as blacklisted, a medium risk will mark it as risky, and a low, contextual or unknown risk will recommend a human review."},"formattedAssociatedAmount":{"type":"string","nullable":true,"description":"A formatted string containing the amount associated with the tax ID appearance on the list; if available. Depending on the list type, this may be a credit, a penalty, a tax return, or a condonation amount."}},"required":["listName","state","dateFirstPublished","yearOfAppearance","reasonOrCause","riskLevel","formattedAssociatedAmount"]},"MexicoBlacklistArticle69BMatch":{"type":"object","properties":{"status":{"type":"string","enum":["Active","UnderInvestigation","Rebutted","CourtOverturned"],"nullable":false,"description":"The status of the appearance in the blacklist. Active means that the tax ID is currently blacklisted, UnderInvestigation means that the tax ID is not yet blacklisted but is under suspicion of performing simulated tax operations, Rebutted means that the taxpayer made a succesful rebuttal of the blacklisting and the SAT reverted it, CourtOverturned means that the tax ID was overturned by a court and the blacklisting was removed."},"makesItBlacklisted":{"type":"boolean","nullable":false,"description":"A flag indicating whether this appearance makes the tax ID blacklisted or not."},"makesItRisky":{"type":"boolean","nullable":false,"description":"A flag indicating whether this appearance makes the tax ID risky or not."},"dateMarkedAsActivelyBlacklisted":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was marked as actively blacklisted in ISO 8601 format as published by the SAT. Null if unknown."},"datePublishedAsActivelyBlacklisted":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was published as actively blacklisted in ISO 8601 format as published on the DOF. Null if unknown."},"dateMarkedAsUnderInvestigation":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was marked as under investigation in ISO 8601 format as published by the SAT. Null if unknown."},"datePublishedAsUnderInvestigation":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was published as under investigation in ISO 8601 format as published on the DOF. Null if unknown."},"dateMarkedAsRebutted":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was marked as rebutted in ISO 8601 format as published by the SAT. Null if unknown."},"datePublishedAsRebutted":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was published as rebutted in ISO 8601 format as published on the DOF. Null if unknown."},"dateMarkedAsCourtOverturned":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was marked as overturned by a court in ISO 8601 format as published by the SAT. Null if unknown."},"datePublishedAsCourtOverturned":{"format":"date-time","type":"string","nullable":true,"description":"The date the tax ID was published as overturned by a court in ISO 8601 format as published on the DOF. Null if unknown."}},"required":["status","makesItBlacklisted","makesItRisky","dateMarkedAsActivelyBlacklisted","datePublishedAsActivelyBlacklisted","dateMarkedAsUnderInvestigation","datePublishedAsUnderInvestigation","dateMarkedAsRebutted","datePublishedAsRebutted","dateMarkedAsCourtOverturned","datePublishedAsCourtOverturned"]},"MexicoTaxListData":{"type":"object","properties":{"isBlacklisted":{"type":"boolean","nullable":false,"description":"A flag indicating whether the tax ID is blacklisted or found on a high risk list."},"isRisky":{"type":"boolean","nullable":false,"description":"A flag indicating that the tax ID is not explicitly blacklisted both appears on a list published by the SAT."},"humanReviewRecommended":{"type":"boolean","nullable":false,"description":"A flag indicating that the tax ID appears on a list published by the SAT and we recommend that an expert reviews the information linked to the tax ID."},"listMatchesForArticle69":{"nullable":false,"description":"List of details of the appearances of this tax ID in the country's Article 69 lists.","type":"array","items":{"$ref":"#/components/schemas/MexicoTaxListArticle69Match"}},"blacklistMatchForArticle69B":{"nullable":true,"description":"Details of the appearance of this tax ID in the country's Article 69-B blacklist. Null if not found.","allOf":[{"$ref":"#/components/schemas/MexicoBlacklistArticle69BMatch"}]}},"required":["isBlacklisted","isRisky","humanReviewRecommended","listMatchesForArticle69","blacklistMatchForArticle69B"]},"ValidationsForMexico":{"type":"object","properties":{"canReceiveInvoices":{"type":"boolean","nullable":true,"description":"A flag indicating whether the tax ID can receive invoices or not. Null if unknown."},"listSearchResult":{"nullable":true,"description":"The result of the SAT list and blacklist search. Null if the search failed or was skipped.","allOf":[{"$ref":"#/components/schemas/MexicoTaxListData"}]}},"required":["canReceiveInvoices","listSearchResult"]},"TaxIdValidationResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"normalizedTaxId":{"type":"string","nullable":false,"description":"The normalized tax ID or the value obtained from the national ID (if applicable)."},"isValid":{"type":"boolean","nullable":false,"description":"A flag indicating whether the tax ID is valid or not."},"personType":{"type":"string","enum":["Individual","Company"],"nullable":true,"description":"The type of person associated with the tax ID. Null if unknown or invalid."},"name":{"type":"string","nullable":true,"description":"The name associated with the tax ID. Null if unknown or invalid."},"mexico":{"nullable":false,"description":"The results of the tax ID validation process for Mexico. Please note this field is only present if the search was performed for Mexico.","allOf":[{"$ref":"#/components/schemas/ValidationsForMexico"}]}},"required":["normalizedTaxId","isValid","personType","name"]},"IdentitySearchParams":{"type":"object","properties":{"firstName":{"type":"string","nullable":false,"description":"The person's given name."},"middleName":{"type":"string","nullable":true,"description":"The person's given middle name or names, if any; null otherwise."},"firstSurname":{"type":"string","nullable":false,"description":"The person's first family name or paternal surname."},"secondSurname":{"type":"string","nullable":true,"description":"The person's second family name or maternal surname, if any; null otherwise."},"dateOfBirth":{"type":"string","nullable":true,"description":"The person's date of birth in the format YYYY-MM-DD, for example: 1990-01-01, 2000-12-05, 2010-06-30. This field can be null or omitted if unknown, but it is highly recommended to provide it for better search results."},"gender":{"type":"string","enum":["Male","Female","Other"],"nullable":true,"description":"The person's gender. This field can be null or omitted if unknown, but it is highly recommended to provide it for better search results."}},"required":["firstName","middleName","firstSurname","secondSurname"]},"EducationSearchParams":{"type":"object","properties":{"country":{"type":"string","enum":["MX"],"nullable":false,"description":"The ISO3166-2 country code of where to make the search/validation."},"nationalId":{"type":"string","nullable":true,"description":"The national ID or equivalent used to uniquely identify a person in a country (e.g., CURP in Mexico). Can be null if another identity element is provided."},"identity":{"nullable":true,"description":"An object containing the personal information used to search in the country's governmental official database. Can be null if a national ID is provided.","allOf":[{"$ref":"#/components/schemas/IdentitySearchParams"}]},"enrichNationalId":{"type":"boolean","nullable":true,"default":true,"description":"A flag that controls whether to query government databases for the personal information of a national ID. If true, the provided identity (such as name and date of birth) might be overridden by the retrieved data and the search will incur in an additional cost; if false, the search will be performed using the personal information and the national ID will be used to match the identity but not enriched. This flag is ignored if no national ID is provided."}},"required":["country","nationalId","identity"]},"EducationHistorySearchRequest":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"An optional UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. If one isn't provided, a new one will be provided as part of the response if the request was successful and `useTransaction` is set to `true`."},"useTransaction":{"type":"boolean","nullable":false,"description":"A boolean value that governs whether the request will create a request-bundling transaction if `transactionUuid` wasn't provided (ignored otherwise). The default is false. It is recommended to use transactions if you will query multiple web services to validate or obtain insights for a single user's identity; by doing so, you can leverage lower pricing (if your plan allows it) and obtain additional data points and better scoring (as we integrate more sources in our data-coherence analysis)."},"requestUuid":{"type":"string","nullable":false,"description":"An optional string containing a UUID provided by your application to leverage idempotency and retrieve the results of the request in case of an interrupted connection."},"searchParams":{"nullable":false,"description":"The search parameters for the education history search request. Please note that using national ID for the search will incur in additional costs.","allOf":[{"$ref":"#/components/schemas/EducationSearchParams"}]}},"required":["searchParams"]},"AcademicDegree":{"type":"object","properties":{"professionalLicenseNumber":{"type":"string","nullable":true,"description":"The professional license number generated by the issuer."},"professionalLicenseType":{"type":"string","nullable":true,"description":"The professional license type generated by the issuer."},"issueDate":{"format":"date-time","type":"string","nullable":true,"description":"The date that the professional license was issued: please note that this doesn't occur at the time of graduation. In ISO 8601 format."},"registrationYear":{"type":"string","nullable":true,"description":"The registration year of the professional license: please note that this doesn't occur at the time of graduation."},"isHigherEducation":{"type":"boolean","nullable":true,"description":"Whether the degree is a higher education degree. False if the person received technical or vocational training. True if the person received a bachelor's or higher degree at a college or university. Null if unknown or if the government database does not include such information."},"isUndergraduate":{"type":"boolean","nullable":true,"description":"A boolean indicating whether the degree is an undergraduate degree. Null if unknown or if the government database does not include such information."},"isPostgraduate":{"type":"boolean","nullable":true,"description":"A boolean indicating whether the degree is a postgraduate degree (master's, doctoral, etc.). Null if unknown or if the government database does not include such information."},"title":{"type":"string","nullable":true,"description":"The title of the degree. In the local language."},"issuer":{"type":"string","nullable":true,"description":"The name of the education institution that issued the degree. In the local language."},"issuerLocation":{"type":"string","nullable":true,"description":"The location of the education institution that issued the degree. In the local language."},"knowledgeArea":{"type":"string","nullable":true,"description":"The knowledge area of the degree. Null if unknown or if the government database does not include such information."},"graduationDate":{"format":"date-time","type":"string","nullable":true,"description":"The date when the education institution reported the graduation to the government database (might be different from the actual graduation date). In ISO 8601 format. Null if unknown or if the government database does not include such information."}},"required":["professionalLicenseNumber","professionalLicenseType","issueDate","registrationYear","isHigherEducation","isUndergraduate","isPostgraduate","title","issuer","issuerLocation","knowledgeArea","graduationDate"]},"EducationHistoryMatch":{"type":"object","properties":{"nameOrNames":{"type":"string","nullable":true,"description":"The name or names of the person."},"firstSurname":{"type":"string","nullable":true,"description":"The first surname of the person."},"secondSurname":{"type":"string","nullable":true,"description":"The second surname of the person."},"dateOfBirth":{"type":"string","nullable":true,"description":"The date of birth of the person in YYYY-MM-DD format."},"gender":{"type":"string","enum":["Male","Female","Other"],"nullable":true,"description":"The gender of the person associated with the identity."},"nationalId":{"type":"string","nullable":true,"description":"The national ID of the person associated with the identity."},"placeOfBirth":{"type":"string","nullable":true,"description":"The place of birth of the person associated with the identity."},"matchConfidenceLevel":{"type":"string","enum":["Low","Medium","High","Very_High","Full"],"nullable":false,"description":"The confidence level of the match based on the comparison with the provided identity data."},"academicDegrees":{"nullable":false,"description":"The list of academic degrees of the person associated with the identity.","type":"array","items":{"$ref":"#/components/schemas/AcademicDegree"}}},"required":["nameOrNames","firstSurname","secondSurname","dateOfBirth","gender","nationalId","placeOfBirth","matchConfidenceLevel","academicDegrees"]},"VeriphOneRequestError":{"type":"object","properties":{"code":{"type":"number","enum":[0,1,2],"nullable":false,"description":"An error code returned by our API, in case the search failed or encountered an issue."},"message":{"type":"string","nullable":false,"description":"An error message returned by our API, in case the search failed or encountered an issue."}},"required":["code","message"]},"IdentityQueryResult":{"type":"object","properties":{"nameOrNames":{"type":"string","nullable":true,"description":"The name or names of the person associated with the identity."},"firstSurname":{"type":"string","nullable":true,"description":"The first surname of the person associated with the identity."},"secondSurname":{"type":"string","nullable":true,"description":"The second surname of the person associated with the identity."},"dateOfBirth":{"type":"string","nullable":true,"description":"The date of birth of the person associated with the identity in YYYY-MM-DD format."},"nationalId":{"type":"string","nullable":true,"description":"The national ID of the person associated with the identity."},"gender":{"type":"string","enum":["Male","Female","Other"],"nullable":true,"description":"The gender of the person associated with the identity."},"placeOfBirth":{"type":"string","enum":["Aguascalientes","Baja California","Baja California Sur","Campeche","Coahuila","Colima","Chiapas","Chihuahua","Ciudad de México","Durango","Guanajuato","Guerrero","Hidalgo","Jalisco","Estado de México","Michoacán","Morelos","Nayarit","Nuevo León","Oaxaca","Puebla","Querétaro","Quintana Roo","San Luis Potosí","Sinaloa","Sonora","Tabasco","Tamaulipas","Tlaxcala","Veracruz","Yucatán","Zacatecas","Nacido en el Extranjero"],"nullable":true,"description":"The place of birth of the person associated with the identity."}},"required":["nameOrNames","firstSurname","secondSurname","dateOfBirth","nationalId","gender","placeOfBirth"]},"EducationHistorySearchMetadata":{"type":"object","properties":{"searchPerformed":{"type":"boolean","nullable":false,"description":"A flag indicating whether the search was performed."},"error":{"nullable":true,"description":"An error object returned by our API, in case the search failed or encountered an issue. Null if no error occurred.","allOf":[{"$ref":"#/components/schemas/VeriphOneRequestError"}]},"identityUsedForSearch":{"nullable":false,"description":"The identity used for the search. When a national ID is provided and enrichment is enabled, this will contain the enriched identity.","allOf":[{"$ref":"#/components/schemas/IdentityQueryResult"}]}},"required":["searchPerformed","error","identityUsedForSearch"]},"EducationHistorySearchResponse":{"type":"object","properties":{"transactionUuid":{"type":"string","nullable":false,"description":"A UUID used to identify a group of identity validation requests as a unique transaction. Used for billing and data-coherence analysis of a single end-user identity. This value is only returned if the request was successful, `useTransaction` was set to `true` and `transactionUuid` was omitted. Pass it to future requests linked to the same user/identity; please note that every web service can only be called once for the same `transactionUuid`."},"searchResults":{"nullable":false,"description":"A list of education history matches found for the provided identity, ordered by confidence level (highest first).","type":"array","items":{"$ref":"#/components/schemas/EducationHistoryMatch"}},"metadata":{"nullable":false,"description":"Metadata about the education history search process.","allOf":[{"$ref":"#/components/schemas/EducationHistorySearchMetadata"}]}},"required":["searchResults","metadata"]},"HealthCheckResponse":{"type":"object","properties":{"module":{"type":"string","description":"Static value that returns this module's name."},"now":{"type":"string","description":"String containing the current date-time in ISO8601 format."}},"required":["module","now"]}}}}