Input Contacts via API

This guide explains how to programmatically import contacts into your HeyGen Personalized Video project via the API.

This feature is available exclusively for Enterprise users.

Create your project via the web interface

The first step is to create a Personalized Video project. You can think of a project as your base template video. By inputing different variables into the projects, you can efficiently create hundreds of different videos.

To create a Personalized Video project, visit HeyGen Personalized Video: Create page and select "Get started" to begin.

On the "Import contacts" page, choose the Import via API option.

Test your API connection

On the API setup page, you need to connect to your API with a test request. To do this, copy the Project ID in this page and add it to project_id parameter in your request and make an initial Add Contact request. After submitting the request, the Connection status should change to Connected within a few seconds if successful.

After completing all the steps and creating a campaign, you can add new contacts to your campaign by making an Add Contact request.

Add Contact

See detailed API reference
Use this request to add contacts to your campaign.

curl --location 'https://api.heygen.com/v1/personalized_video/add_contact' \
--header 'accept: application/json' \
--header 'x-api-key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "project_id": "<project_id>",
  "variables_list": [
    {
      "first_name": "value1",
      "email": "[email protected]"
    }
  ]
}'
{
  "code": 100,
  "data": null,
  "msg": null,
  "message": "<message>"
}
  • project_id: The unique identifier for your project. This ID links the contact to the specific project you have created.
  • variables_list: A list of objects, each representing a contact to be added to the project. You can include additional fields in the variables_list objects depending on the personalization variables defined in your campaign.

Conclusion

This guide has outlined the steps to input contacts into your HeyGen Personalized Video project via API. By following these steps, you can programmatically input contacts into your project from any source.