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: - 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. - 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. Please 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. Please 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. Please 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: - Mexico: OCR (Comisión Federal de Electricidad / CFE, Telmex, Telcel, Megacable, Sky, Izzi) & Attestation (Comisión Federal de Electricidad / CFE). Please 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: 1. The details obtained from the OCR (if the document type is supported and valid). 2. The results of the attestation against the entity or authority that generates this type of document. 3. 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: 1. The file is empty or not a valid base64 string. Error code 70012. 2. The file is corrupted or unreadable. Error code 70015. 3. 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. Send a PDF or JPG file of a proof-of-address document to extract its contents using Optical Character Recognition (OCR). Supported types: - Mexico: OCR (Comisión Federal de Electricidad / CFE, Telmex, Telcel, Megacable, Sky, Izzi). Please 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/ProofOfAddressOcrResponseV1_0_0' '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: 1. The file is empty or not a valid base64 string. Error code 70012. 2. The file is corrupted or unreadable. Error code 70015. 3. The document type is unsupported or invalid. Error code 70011. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Proof of address OCR (v1.0.0) 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. Trigger 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: - Mexico: Attestation (Comisión Federal de Electricidad / CFE). Please 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: - Mexico: RFC or CURP (When using CURP, the tax ID number will be built from scratch and might lead to a lower accuracy). Please 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: - Mexico (your application can provide a full name (and optional date of birth) or a national ID (CURP) to perform the search). Please 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' '408': description: >- The search request exceeded the configured timeout. Consider retrying with a higher `options.timeoutInSeconds` value or enable `options.useCache` to fall back to a previously cached result when available. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '424': description: >- The educational records service is currently unreachable or undergoing maintenance. Retry later; if caching is enabled, a previously cached result may still be returned as part of a 200 response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- An unexpected error occurred while communicating with the external records service. Retry later. 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). # Introduction This API is grouped into specific categories based on common platform use-cases; for example: - 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. - The **Helper Services** section aggregates endpoints used for more complex interactions with our platforms where you want to go beyond our SDK's functionality. - The **Identity Validation** category aggregates endpoints relevant to complement identity verifications during a KYC flow. - 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. - Lastly, the **Misc** category is used to interact and monitor our infrastructure. # OpenAPI Specification This 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. # Authentication The 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. # Versioning Our 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. 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: Quick search: Adobe, 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. Deep search only: 1Win, 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: - [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 - live-data-3 - id-verification 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 NumberLiveDataTier3: type: object properties: {} 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' carrierIdentityVerificationStatus: type: string enum: - NOT_VERIFIED - VERIFIED - INCOMPLETE - INVALID - RESERVED nullable: true description: >- A string that determines the current state of the number's KYC process with the carrier. Available only for Mexico. Null if unknown or the carrier is unsupported. Included if the id-verification data package is included, omitted otherwise. 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. Included if the Pro data package is included, null otherwise. allOf: - $ref: '#/components/schemas/NumberLiveDataTier2' liveDataTier3: nullable: true description: >- Additional phone number metadata linked to the phone number's type of service and current status with the carrier. Included if the live-data-3 data package is included, omitted otherwise. allOf: - $ref: '#/components/schemas/NumberLiveDataTier3' 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. - A value of 0 means that the municipality has the lowest criminal incidence among all municipalities nationwide. - A value of 100 indicates the highest criminal incidence in the entire country. - 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. - A value of 0 means that the municipality has the lowest criminal incidence in its state. - A value of 100 indicates the highest criminal incidence in the state. - 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 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 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 MultiIssuerOcrServiceDetails: 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 MultiIssuerOcrExtractionResult: 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' 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. serviceDetails: nullable: true description: OCR-read issuer-specific fields. allOf: - $ref: '#/components/schemas/MultiIssuerOcrServiceDetails' required: - issuer - clientName - address - issuanceDate - paymentExpectedBy - paymentOverdueDate - billingPeriod - amountDue - serviceDetails CoherenceCheckV1_0_0: type: object properties: title: type: string enum: - ServiceNumber - Date - NumericalId - Rmu - PricingType - AmountDue - Barcode - 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 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`. 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' ocrExtractedData: nullable: false description: An object containing the data extracted from the document via OCR. allOf: - $ref: '#/components/schemas/MultiIssuerOcrExtractionResult' 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/CoherenceCheckV1_0_0' 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: - validityChecks - ocrExtractedData - basicCoherenceChecks - 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 ProofOfAddressOcrResponseV1_0_0: 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`. 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' ocrExtractedData: nullable: false description: An object containing the data extracted from the document via OCR. allOf: - $ref: '#/components/schemas/MultiIssuerOcrExtractionResult' 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/CoherenceCheckV1_0_0' required: - validityChecks - ocrExtractedData - basicCoherenceChecks 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 SearchOptions: type: object properties: useCache: type: boolean nullable: false default: true description: >- A flag that controls whether to use the cache or not for this search operation. Cache is only used when the third-party API and all of its fallbacks are down or unavailable. staleThresholdInDays: type: number nullable: false minimum: 30 maximum: 3650 default: .inf description: >- The threshold in days after which the cache is considered stale for this search operation and ignored. If unset, the cache will never be considered stale. Value must be an integer. Ignored if useCache is false. timeoutInSeconds: type: number minimum: 3 maximum: 3600 nullable: false description: >- An optional value that governs how long the service will wait for a response from the education authority's search service. 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 30 seconds. The value must be an integer between 3 and 3600. Please note that this timeout is applied to the search request itself, not to the entire operation; and it does not include the time it takes to enrich the identity, if applicable. 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' options: nullable: false description: >- An optional object that contains configuration options for the search operation, such as the timeout or whether to use the cache or not. allOf: - $ref: '#/components/schemas/SearchOptions' 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 - 3 nullable: false description: >- An error code returned by our API, in case the search failed or encountered an issue. Possible values: 0 (NoError), 1 (InvalidIdentityData), 2 (SearchServiceUnavailable), 3 (SearchServiceTimedOut). 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' usedCacheTimestamp: format: date-time type: string nullable: true description: >- The timestamp of the cached record (ISO 8601 format) that was used for this search operation. Null if no cache was used. required: - searchPerformed - error - identityUsedForSearch - usedCacheTimestamp 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