Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

SendNotifyCodeVerification

Generates a one-time passcode and delivers it to a recipient over the requested channel. The passcode policy is captured from the referenced notify code configuration at the time of the request, so later updates to the configuration do not affect verifications that are already in progress.

Request Syntax


POST /v1/notify-code-verifications/send HTTP/1.1
Content-type: application/json

{
   "channel": "string",
   "configurationSetName": "string",
   "context": { 
      "string" : "string" 
   },
   "destinationIdentity": "string",
   "notifyCodeConfiguration": "string",
   "originationIdentity": "string",
   "overrideChannelParameters": { 
      "notify": { 
         "notifyTemplateId": "string",
         "voiceId": "string"
      },
      "text": { 
         "destinationCountryParameters": { 
            "string" : "string" 
         },
         "inlineTemplateBody": "string"
      },
      "voice": { 
         "inlineTemplateBody": "string",
         "languageCode": "string",
         "voiceId": "string",
         "voiceMessageBodyTextType": "string"
      },
      "whatsApp": { 
         "languageCode": "string",
         "whatsAppTemplateName": "string"
      }
   },
   "overrideCodeConfigurationParameters": { 
      "codeLength": number,
      "codeType": "string",
      "maxAttempts": number,
      "validityPeriodMinutes": number
   },
   "referenceId": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

channel

The channel used to deliver the one-time passcode to the recipient.

Type: String

Valid Values: TEXT | VOICE | WHATSAPP

Required: Yes

configurationSetName

The name of the configuration set used to control how delivery events for the message are handled.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [A-Za-z0-9_-]+

Required: No

context

A map of custom key and value pairs that are propagated to the delivery events for this verification.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 5 items.

Key Length Constraints: Minimum length of 1. Maximum length of 100.

Key Pattern: \S+

Value Length Constraints: Minimum length of 1. Maximum length of 800.

Value Pattern: \S(?:[\s\S]*\S)?

Required: No

destinationIdentity

The recipient identifier. For the TEXT and VOICE channels, specify an E.164 phone number. For the WhatsApp channel, specify a WhatsApp address.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 20.

Pattern: [\x21-\x22\x24-\x7E]+

Required: Yes

notifyCodeConfiguration

The identifier or Amazon Resource Name (ARN) of the notify code configuration that supplies the passcode policy and template defaults. When you do not specify a configuration, you must supply the template in the request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [A-Za-z0-9_:/-]+

Required: No

originationIdentity

The identity used to send the message, such as a phone number, sender ID, or pool that is owned by your account.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [A-Za-z0-9_:/+-]+

Required: Yes

overrideChannelParameters

The channel-specific parameters used to render and deliver the one-time passcode for this request. The route that is derived from the channel and the origination identity selects the matching channel. When you do not specify channel parameters, the service uses the parameters from the referenced notify code configuration.

Type: ChannelParameters object

Required: No

overrideCodeConfigurationParameters

The per-send overrides for the passcode policy parameters, including the code type, length, validity period, and maximum number of attempts. These values override the values from the referenced notify code configuration. When you do not specify a value, the value from the configuration is used, and if neither is set, the service default applies.

Type: CodeConfigurationParameters object

Required: No

referenceId

A caller-supplied reference identifier that binds a send request to a later validate request. Specify the same value in both requests.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [A-Za-z0-9_-]+

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "messageId": "string",
   "verificationId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

messageId

The service-generated identifier for the message that delivers the one-time passcode.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [A-Za-z0-9_:/-]+

verificationId

The service-generated identifier for the verification.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [A-Za-z0-9_:/-]+

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

ConflictException

The request conflicts with the current state of the resource.

resourceId: The identifier of the resource that the request conflicts with.
resourceType: The type of the resource that the request conflicts with.

HTTP Status Code: 409

InternalServerException

An unexpected error occurred during the processing of the request.

HTTP Status Code: 500

ResourceNotFoundException

The request references a resource that does not exist. Verify that the resource identifier is correct and try your request again.

resourceId: The identifier of the resource that could not be found.
resourceType: The type of the resource that could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The request would exceed a service quota for your account.

HTTP Status Code: 400

ThrottlingException

The request was denied because it exceeded the allowed request rate.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints specified by the service. Check your request parameters and retry the request.

HTTP Status Code: 400