> ## Documentation Index > Fetch the complete documentation index at: https://docs.prelude.so/llms.txt > Use this file to discover all available pages before exploring further. # Create or retry a verification > Create a new verification for a specific phone number. If another non-expired verification exists (the request is performed within the verification window), this endpoint will perform a retry instead. ```javascript Node.js theme={null} import Prelude from "@prelude.so/sdk"; const client = new Prelude(); async function main() { const verification = await client.verification.create({ target: { type: "phone_number", value: "+30123456789", }, }); console.log(verification.id); } main(); ``` ```go Go theme={null} package main import ( "context" "fmt" "github.com/prelude-so/go-sdk" "github.com/prelude-so/go-sdk/option" ) func main() { client := prelude.NewClient() verification, err := client.Verification.New(context.TODO(), prelude.VerificationNewParams{ Target: prelude.F(prelude.VerificationNewParamsTarget{ Type: prelude.F(prelude.VerificationNewParamsTargetTypePhoneNumber), Value: prelude.F("+30123456789"), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", verification.ID) } ``` ```python Python theme={null} import os from prelude_python_sdk import Prelude client = Prelude() verification = client.verification.create( target={ "type": "phone_number", "value": "+30123456789", }, ) print(verification.id) ``` ```java Java theme={null} import so.prelude.sdk.client.PreludeClient; import so.prelude.sdk.client.okhttp.PreludeOkHttpClient; import so.prelude.sdk.models.VerificationCreateParams; import so.prelude.sdk.models.VerificationCreateResponse; // Configures using the `API_TOKEN` environment variable PreludeClient client = PreludeOkHttpClient.fromEnv(); VerificationCreateParams params = VerificationCreateParams.builder() .target(VerificationCreateParams.Target.builder() .type(VerificationCreateParams.Target.Type.PHONE_NUMBER) .value("+30123456789") .build()) .build(); VerificationCreateResponse verification = client.verification().create(params); ``` ```ruby Ruby theme={null} require "bundler/setup" require "prelude_sdk" prelude = PreludeSDK::Client.new( api_token: ENV["API_TOKEN"] # This is the default and can be omitted ) verification = prelude.verification .create(target: {type: "phone_number", value: "+30123456789"}) puts(verification.id) ``` ## OpenAPI ````yaml post /v2/verification openapi: 3.1.0 info: title: Prelude API version: 2.0.0 description: The Prelude API allows you to send messages to your users. contact: email: support@prelude.so servers: - url: https://api.prelude.dev description: Production server security: - apiToken: [] tags: - name: Notify description: Send transactional and marketing messages with compliance enforcement. - name: Transactional description: Send transactional messages (deprecated - use Notify API instead). - name: Verify description: Verify phone numbers. - name: Watch description: Evaluate email addresses and phone numbers for trustworthiness. - name: Lookup description: >- Retrieve detailed information about a phone number including carrier data, line type, and portability status. paths: /v2/verification: post: tags: - Verify summary: Create or retry a verification description: >- Create a new verification for a specific phone number. If another non-expired verification exists (the request is performed within the verification window), this endpoint will perform a retry instead. operationId: createVerification requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVerificationRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateVerificationResponse' '400': description: KO content: application/json: schema: $ref: '#/components/schemas/Error' callbacks: webhook_event: '{$request.body#/options/callback_url}': post: parameters: - in: header name: X-Webhook-Signature schema: type: string description: >- The signature of the webhook event. It is the base64 URL-encoded RSASSA-PSS signature of the sha256 of the body of the request prefixed with "rsassa-pss-sha256=". To activate this feature, generate a webhook key from your Dashboard. examples: - >- rsassa-pss-sha256=Xy8pCJUV/UvCnZrTgk5tK5D+0rivHVYChQ50cwabCqdXVTIHujuTEH8hTCgYiwBQcnaNXKl6Oz+AoXWUtpaHcQiyzifUAS6EL5a8XBaIr1cVKk0yOgrvSjtw4QBTBwqVfrXZr33wmh3bAqDf5uIPc3beIOLLHh08r+FLfy+YvKZ3DjZ7WNuLFLfU/NYrG2zC1uhHTMKIKFyP6D2GOHvqn1BN5I/nWtDDlhI6oId6Yv/lnHc6ac1IPyQWgHRTWY0r6rFcrFtak29e2drP7PMG5+sxhV3F/NactkdM9rQ3FH7HqgFFFglU/2UbNpAmTS4y7363SaZ3m71H+q7H1Ks3oQ== requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' responses: '200': description: Your server accepted the event and will process it. default: description: >- Your server did not accept the event and we will retry for 24 hours. components: schemas: CreateVerificationRequest: type: object properties: target: $ref: '#/components/schemas/Target' description: >- The verification target. Either a phone number or an email address. To use the email verification feature contact us to discuss your use case. signals: $ref: '#/components/schemas/Signals' options: type: object description: Verification options properties: template_id: type: string description: >- The identifier of a verification template. It applies use case-specific settings, such as the message content or certain verification parameters. examples: - prelude:psd2 - 8f0b8fdd-c2cb-4387-b20a-56e9b2e5a0d2 variables: type: object description: The variables to be replaced in the template. additionalProperties: type: string examples: - foo: bar method: type: string default: auto enum: - auto - voice - message description: > The method used for verifying this phone number. The 'voice' option provides an accessible alternative for visually impaired users by delivering the verification code through a phone call rather than a text message. It also allows verification of landline numbers that cannot receive SMS messages. The 'message' option explicitly requests message delivery (SMS, WhatsApp ...) and skips silent verification, useful for scenarios requiring direct user interaction. locale: type: string description: >- A BCP-47 formatted locale string with the language the text message will be sent to. If there's no locale set, the language will be determined by the country code of the phone number. If the language specified doesn't exist, it defaults to US English. examples: - el-GR sender_id: type: string description: >- The Sender ID to use for this message. The Sender ID needs to be enabled by Prelude. app_realm: type: object description: >- This allows automatic OTP retrieval on mobile apps and web browsers. Supported platforms are Android (SMS Retriever API) and Web (WebOTP API). required: - platform - value properties: platform: type: string enum: - android - web description: >- The platform for automatic OTP retrieval. Use "android" for the SMS Retriever API or "web" for the WebOTP API. examples: - android value: type: string description: > The value depends on the platform: - For Android: The SMS Retriever API hash code (11 characters). See [Google documentation](https://developers.google.com/identity/sms-retriever/verify#computing_your_apps_hash_string). - For Web: The origin domain (e.g., "example.com" or "www.example.com"). See [WebOTP API documentation](https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API). code_size: type: integer description: >- The size of the code generated. It should be between 4 and 8. Defaults to the code size specified from the Dashboard. examples: - 5 minimum: 4 maximum: 8 custom_code: type: string description: >- The custom code to use for OTP verification. To use the custom code feature, contact us to enable it for your account. For more details, refer to [Custom Code](/verify/v2/documentation/custom-codes). examples: - '123456' - abc123 minLength: 4 maxLength: 8 callback_url: type: string description: >- The URL where webhooks will be sent when verification events occur, including verification creation, attempt creation, and delivery status changes. For more details, refer to [Webhook](/verify/v2/documentation/webhook). preferred_channel: type: string description: The preferred channel to be used in priority for verification. enum: - sms - rcs - whatsapp - viber - zalo - telegram metadata: type: object description: >- The metadata for this verification. This object will be returned with every response or webhook sent that refers to this verification. properties: correlation_id: type: string description: >- A user-defined identifier to correlate this verification with. It is returned in the response and any webhook events that refer to this verification. maxLength: 80 dispatch_id: type: string description: The identifier of the dispatch that came from the front-end SDK. examples: - 123e4567-e89b-12d3-a456-426614174000 minLength: 36 maxLength: 36 required: - target CreateVerificationResponse: type: object properties: id: type: string examples: - vrf_01jc0t6fwwfgfsq1md24mhyztj description: The verification identifier. status: type: string examples: - success enum: - success - retry - challenged - blocked - shadow_blocked description: | The status of the verification. * `success` - A new verification window was created. * `retry` - A new attempt was created for an existing verification window. * `challenged` - The verification is suspicious and is restricted to non-SMS and non-voice channels only. This mode must be enabled for your customer account by Prelude support. * `blocked` - The verification was blocked. * `shadow_blocked` - The verification triggered a block rule but the decision was not enforced; this is used to dry-run anti-fraud configuration. This mode must be enabled for your customer account by Prelude support. reason: type: string enum: - expired_signature - in_block_list - invalid_phone_line - invalid_phone_number - invalid_signature - repeated_attempts - suspicious description: > The reason why the verification was blocked. Only present when status is "blocked" or "shadow_blocked". * `expired_signature` - The signature of the SDK signals is expired. They should be sent within the hour following their collection. * `in_block_list` - The phone number is part of the configured block list. * `invalid_phone_line` - The phone number is not a valid line number (e.g. landline). * `invalid_phone_number` - The phone number is not a valid phone number (e.g. unallocated range). * `invalid_signature` - The signature of the SDK signals is invalid. * `repeated_attempts` - The phone number has made too many verification attempts. * `suspicious` - The verification attempt was deemed suspicious by the anti-fraud system. examples: - invalid_phone_number risk_factors: type: array items: type: string enum: - behavioral_pattern - device_attribute - fraud_database - location_discrepancy - network_fingerprint - poor_conversion_history - prefix_concentration - suspected_request_tampering - suspicious_ip_address - temporary_phone_number description: > The risk factors that contributed to the verification being blocked. Only present when status is "blocked" or "shadow_blocked" and the anti-fraud system detected specific risk signals. * `behavioral_pattern` - The phone number past behavior during verification flows exhibits suspicious patterns. * `device_attribute` - The device exhibits characteristics associated with suspicious activity patterns. * `fraud_database` - The phone number has been flagged as suspicious in one or more of our fraud databases. * `location_discrepancy` - The phone number prefix and IP address discrepancy indicates potential fraud. * `network_fingerprint` - The network connection exhibits characteristics associated with suspicious activity patterns. * `poor_conversion_history` - The phone number has a history of poorly converting to a verified phone number. * `prefix_concentration` - The phone number is part of a range known to be associated with suspicious activity patterns. * `suspected_request_tampering` - The SDK signature is invalid and the request is considered to be tampered with. * `suspicious_ip_address` - The IP address is deemed to be associated with suspicious activity patterns. * `temporary_phone_number` - The phone number is known to be a temporary or disposable number. examples: - - suspicious_ip_address - fraud_database method: type: string enum: - email - message - silent - voice description: The method used for verifying this phone number. channels: type: array items: type: string enum: - rcs - silent - sms - telegram - viber - voice - whatsapp - zalo description: The ordered sequence of channels to be used for verification silent: type: object description: The silent verification specific properties. properties: request_url: type: string description: The URL to start the silent verification towards. required: - request_url metadata: type: object description: The metadata for this verification. properties: correlation_id: type: string description: >- A user-defined identifier to correlate this verification with. It is returned in the response and any webhook events that refer to this verification. maxLength: 80 request_id: type: string required: - id - method - status Error: type: object properties: code: type: string description: The error code. examples: - invalid_phone_number message: type: string examples: - >- The provided phone number is invalid. Provide a valid E.164 phone number. description: A human-readable message describing the error. type: type: string examples: - bad_request description: The error type. request_id: type: string examples: - 3d19215e-2991-4a05-a41a-527314e6ff6a description: >- A string that identifies this specific request. Report it back to us to help us diagnose your issues. required: - code - message - type Target: type: object description: The operation target. Either a phone number or an email address. properties: type: type: string enum: - phone_number - email_address description: The type of the target. Either "phone_number" or "email_address". value: type: string examples: - '+30123456789' - mail@example.com description: An E.164 formatted phone number or an email address. required: - type - value Signals: type: object description: >- The signals used for anti-fraud. For more details, refer to [Signals](/verify/v2/documentation/prevent-fraud#signals). properties: ip: type: string format: ipv4 description: >- The public IP v4 or v6 address of the end-user's device. You should collect this from your backend. If your backend is behind a proxy, use the `X-Forwarded-For`, `Forwarded`, `True-Client-IP`, `CF-Connecting-IP` or an equivalent header to get the actual public IP of the end-user's device. examples: - 203.0.113.123 device_id: type: string description: >- A unique ID for the user's device. You should ensure that each user device has a unique `device_id` value. Ideally, for Android, this corresponds to the `ANDROID_ID` and for iOS, this corresponds to the `identifierForVendor`. examples: - 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: The type of the user's device. examples: - ios device_model: type: string description: The model of the user's device. examples: - iPhone17,2 os_version: type: string description: The version of the user's device operating system. examples: - 18.0.1 app_version: type: string description: The version of your application. examples: - 1.2.34 user_agent: type: string description: >- The user agent of the user's device. If the individual fields (os_version, device_platform, device_model) are provided, we will prioritize those values instead of parsing them from the user agent string. examples: - >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 ja4_fingerprint: type: string description: >- The JA4 fingerprint observed for the end-user's connection. Prelude will infer it automatically when you use our Frontend SDKs (which use Prelude's edge network), but you can also forward the value if you terminate TLS yourself. examples: - t13d1516h2_8daaf6152771_e5627efa2ab1 is_trusted_user: type: boolean description: >- This signal should indicate a higher level of trust, explicitly stating that the user is genuine. Contact us to discuss your use case. For more details, refer to [Signals](/verify/v2/documentation/prevent-fraud#signals). examples: - false securitySchemes: apiToken: type: http scheme: bearer ````