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.

There is a throttling limit placed on usage of the API that includes a RateLimit of 2 per second, and a BurstLimit of 5 per second.

If you are using an IAM account, it must have permissions 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 can include only alphanumeric, dash, and underscore characters.

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

Attributes:[ { "customerName" : "John Stiles" }, ]

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.

Type: String

Length Constraints: Maximum length of 500.

Required: No


The identifier for the contact flow to execute for the outbound call. This is a GUID value only. Amazon Resource Name (ARN) values are not supported.

To find the ContactFlowId, open the contact flow to use in the Amazon Connect contact flow designer. The ID for the contact flow is displayed in the address bar as part of the URL. For example, an address displayed when you open a contact flow is similar to the following:

At the end of the URL, you see:


The ContactFlowID for this contact flow is:


Make sure to include only the GUID after the "contact-flow/" in your requests.

Type: String

Length Constraints: Maximum length of 500.

Required: Yes


The phone number, in E.164 format, of the customer to call with the outbound contact.

Type: String

Required: Yes


The identifier for your Amazon Connect instance. To find the InstanceId value for your Amazon Connect instance, open the Amazon Connect console. Select the instance alias of the instance and view the instance ID in the Overview section. 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

Required: Yes


The queue to which to add the call. If you specify a queue, the phone displayed for caller ID is the phone number defined for the queue. If you do not specify a queue, the queue used is the queue defined in the contact flow specified by ContactFlowId.

To find the QueueId, open the queue 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 QueueId value is the set of characters at the end of the URL, after "queue/", such as aeg40574-2d01-51c3-73d6-bf8624d2168c.

Type: String

Required: No


The phone number, in E.164 format, associated with your Amazon Connect instance to use to place the outbound call.

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 for your instance. You can request that the country be included in the allowed countries for your instance by submitting a Service Limit Increase.

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 limit exceeded the maximum allowed active calls in a queue.

HTTP Status Code: 429


The contact is not permitted because outbound calling is not enabled for the instance.

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: