Amazon Connect Service
API Reference (API Version 2017-08-08)


The StartOutboundVoiceContact operation initiates a contact flow to place an outbound call to a customer.

If you are using an IAM account, it must have permission to the connect:StartOutboundVoiceContact action.

Request Syntax

PUT /contact/outbound-voice HTTP/1.1 Content-type: application/json { "Attributes": { "string" : "string" }, "ClientToken": "string", "ContactFlowId": "string", "DestinationPhoneNumber": "string", "InstanceId": "string", "QueueId": "string", "SourcePhoneNumber": "string" }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.


Specify a custom key-value pair using an attribute map. The attributes are standard Amazon Connect attributes, and can be accessed in contact flows just like any other contact attributes.

There can be up to 32,768 UTF-8 bytes across all key-value pairs. Attribute keys must include only alphanumeric, dash, and underscore characters.

For example, if you want play a greeting when the customer answers the call, you can pass the customer name in attributes similar to the following:

Type: String to string map

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

Value Length Constraints: Minimum length of 0. Maximum length of 32767.

Required: No


A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. The token is valid for 7 days after creation. If a contact is already started, the contact ID is returned. If the contact is disconnected, a new contact is started.

Type: String

Length Constraints: Maximum length of 500.

Required: No


To find the ContactFlowId, open the contact flow you want to use in the Amazon Connect contact flow designer. Under the name of the contact flow, choose Show additional flow information. The ARN for the contact flow is displayed. The ID for the contact flow is included in the ARN. For example, the contact flow ID is the set of characters at the end of the ARN, after contact-flow/ such as 78ea8fd5-2659-4f2b-b528-699760ccfc1b.

Only contact flows of type "Contact flow" are supported when using the StartOutboundVoiceContact operation. The type for a contact flow is displayed in the Type column when you view the contact flows in your instance. It is also displayed above the ARN when you choose "Display additional flow information" for a contact flow open in the designer.

Type: String

Length Constraints: Maximum length of 500.

Required: Yes


The phone number of the customer in E.164 format.

Type: String

Required: Yes


The identifier for your Amazon Connect instance. To find the ID of your instance, open the AWS console and select Amazon Connect. Choose the alias of the instance in the Instance alias column. The instance ID is displayed in the Overview section of your instance settings. For example, the instance ID is the set of characters at the end of the instance ARN, after instance/, such as 10a4c4eb-f57e-4d4c-b602-bf39176ced07.

Type: String

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

Required: Yes


If included in the request, sets the default queue. If a queue is specified in the contact flow, that queue overrides the queue set by the QueueId parameter. If you do not include a QueueId in the request, the queue used is the one defined in the contact flow.

If you include a QueueId in the request, the phone number displayed as the outbound caller ID number is the Outbound caller ID number specified in the queue settings. If you include a SourcePhoneNumber parameter in the request, the caller ID is the number specified for SourcePhoneNumber, which overrides the caller ID number set for the queue.

To find the QueueId, open the queue you want to use in the Amazon Connect Queue editor. The ID for the queue is displayed in the address bar as part of the URL. For example, the queue ID is the set of characters at the end of the URL, after 'queue/' such as queue/aeg40574-2d01-51c3-73d6-bf8624d2168c.

Type: String

Required: No


The phone number, in E.164 format, associated with your Amazon Connect instance to use for the outbound call. If specified, this is also the number used for the caller ID number displayed to the recipient.

Type: String

Required: No

Response Syntax

HTTP/1.1 200 Content-type: application/json { "ContactId": "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.


The unique identifier of this contact within your Amazon Connect instance.

Type: String

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


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


Outbound calls to the destination number are not allowed.

HTTP Status Code: 403


Request processing failed due to an error or failure with the service.

HTTP Status Code: 500


One or more of the parameters provided to the operation are not valid.

HTTP Status Code: 400


The request is not valid.

HTTP Status Code: 400


The allowed limit for the resource has been reached.

HTTP Status Code: 429


The contact is not permitted.

HTTP Status Code: 403


The specified resource was not found.

HTTP Status Code: 404


Example policy that grants permissions for this operation to a specific Amazon Connect instance:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "connect:StartOutboundVoiceContact" ], "Resource": "arn:aws:connect:us-west-2:854005473701:instance/97940ff5-2ce5-424b-a570-8d954e6862bd/contact/*" } ] }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: