Skip to Main Content

Update Contact Attributes API

Released in September 2018, the Contact API for Amazon Connect can be used to update and create new contact attributes. In case you're not familiar with the term, contact attributes are Key Value Pairs that can be used to store data up to 32767 characters in length and include information such as the name of the caller and why they called.


 keyName : KeyValue
 customerName : John Smith

Contact attributes are stored with the Contact Trace Record (CTR), and are available within Amazon Connect for 24 months. The attributes are also available within the Kinesis streams, which are used to populate Enterprise Data Warehouses (EDWs) and drive communications for post contact text messages, surveys, etc.

How can I use this new API?

Until now, amending contact attributes was limited to being completed in real-time within the IVR (Contact Flows/LEX). With this release, we can now update/create contact attributes at any(1) time. You can do this via different methods such as:

  • EVENT DRIVEN: Using AWS Lambda to react to an event and update the contact attributes.
  • PROCESS DRIVEN: Using AWS Step Functions to poll for information and once received then posting the update to the contact attributes.
  • REAL TIME: Having the Agent / Agent UI sending updates to the contact attributes.

Some use cases:

After thinking about this a little, I have come up with a few use cases. You'll have many more innovative ideas I'm sure!

  • Parallel logic processing during IVR
    • Currently, when you make a lambda call, the contact will wait at that step for the reply. If you have a back-end process that takes a long time (Amazon Connect to Lambda allows a maximum of 8 second wait), but is not critical for the customer journey at this stage, then you could fire off a request and allows the back-end processes to update the contact attributes when ready (step functions or event-driven). You could then query these later during the transaction or on the agents' screen etc..
  • Updates are driven by agent
    • Call Pegging (Reason for Calling)
    • Leave notes
    • Tag calls (Abusive callers / QA Flags etc.)
    • Set call-back date/time (then use the OB API to call the customer back)
  • Updates are driven by agent desktop (no manual effort required)
    • Link customer account to the Contact Trace Record (if identification was not found during IVR)
    • Share other business data to assist with post-processing (as the data will be in the Kinesis Stream)

Some code and examples:

If you're like me and like the simplicity of python for demo and readability, this is all you need.

import boto3
client = boto3.client('connect')

response = client.update_contact_attributes(
 'attributeName': 'testing of the update_contact_attributes API'

Please note the InitialContactId and InstanceId will be specific for your Amazon Connect instance and the contact record you want to update. Once I run this I can see the results instantaneously within the Contact Search menu within the Connect UI:

updated contact attributes image

Then I can run it again and over-write as such:

updated contact attributes image

For the agent-driven events, below is a simple example of Call Pegging where the agent will simply select the reason for calling from the drop-down and press save. Also included is an abusive caller button, which sets an attribute, but you can also have the call disconnected - it all depends on your requirements.

Custom CCP Buttons


  • Brew runs N-10 (urgh) which as of today is version 1.16.10 but you need at least aws-cli/1.16.13 to use this API
  • Standard Libraries within Lambda should be checked DOCS
    • Ensure you INCLUDE the AWS SDK until the Lambda version supports the API Method
  • The full API definition can be found within the Connect documentation here.


How you design and build to use this, and the other API features of Amazon Connect, will vary from use-case to use-case and from customer to customer. If you need support for development of a custom application, get in touch with us!

As you can see this simple new Contact API brings a multitude of design options as you build and grow with Amazon Connect. It can be used to drive automation, enhance the customer/agent experience as well as to improve data richness. We'd love to hear about your ideas, so please ping us on twitter or Contact Us.

(1) Contacts made prior to the API release cannot be amended. Connect stores contact trace records for 24 months and if you take a copy of the CTR via Kinesis Streams that copy is a point in time version, but an updated CTR event is set to the Stream.