Autofill guide

This guide demonstrates how you can generate dynamic designs in Canva using brand templates, autofill, and the Connect APIs.

The following example generates a design based on variables from a custom data source. A city name and weather information from a dataset is sent to the API in a request, and then the supplied information is applied to a template to create a new design.

Prerequisites

To complete this guide, you need:

1. An account on https://www.canva.com/developers.
2. A Canva Developer integration with the required permissions (also known as scopes).
3. Access to the data autofill and brand templates features in Canva (requires an Enterprise subscription).

Prepare your template

Canva provides two options for setting up autofillable brand templates in your Canva account. You can create a template from scratch using the Canva editor, or, use a sample template, which you can add to your Canva account. Using a sample template gets you started quicker, but developing one from scratch gives you a better understanding of the full user experience.

Option 1. Create an autofillable template from scratch

The following steps walk you through creating a design template, configuring the Data Autofill app, and publishing your design as a brand template.

Step 1. Create the template design

1. Log in to your Canva account with an account that has access to the data autofill and brand templates features.

2. Create a Presentation (16:9) design with two text blocks at the top of the canvas:

   1. In the first frame, add the text: "Good Morning"
   2. In the second frame, add the text: City

3. Add two more text blocks to the bottom of the canvas:

   1. In the first block, add the text: "It's going to be".
   2. In the second block, add the text: Temperature. You can style the text however you want.

4. Add an empty picture frame and fit it to the size of the canvas. If the frame covers your text frames, select the picture frame, click Position, and in the Arrange tab, click To back.

   Your design should look something like the following screenshot.

   

Step 2. Configure the Data Autofill app

1. In Canva, click Apps and search for "Data Autofill".

2. Click Open and select Custom as your data source.

3. In the screen that says "Connect Canva to a custom data source", click Continue.

4. Select the text frame with the placeholder City you previously created. Click the Data Field button.

   

   Where it says "Enter data field name" type CITY. Repeat this step for the frame with the placeholder text Temperature, typing TEMPERATURE where it says "Enter data field name".

5. Select the picture frame you previously added to cover the background of your design. Click the Data Field button, and type BACKGROUND where it says "Add new".

6. In the Data autofill app, you should have 3 data fields: CITY, TEMPERATURE and BACKGROUND. These are preconfigured as text and image fields, which define (and limit) the type of data they accept when filled with the API.

   

Step 3. Publish your design as a brand template

1. Publish your design as a brand template and note the brand template ID. Locate the brand template ID by examining the URL of your brand template. For example, in the URL https://www.canva.com/design/ABCDE12345/ev0WJLWHJF9_FCFTieQf_g/edit the brand template ID is the ABCDE12345 string in the middle of the URL.
2. Save the ID so you can query it later with the API.

Option 2. Use a sample template

The following steps describe how to use a sample template pre-configured with autofillable data fields.

Step 1. Copy the sample template to your Canva account

1. Open the sample template.
2. Click Use template for new design.

Step 2. Publish your design as a brand template

1. Publish your design as a brand template and note the brand template ID. Locate the brand template ID by examining the URL of your brand template. For example, in the URL https://www.canva.com/design/ABCDE12345/ev0WJLWHJF9_FCFTieQf_g/edit the brand template ID is the ABCDE12345 string in the middle of the URL.
2. Save the ID so you can query it later with the API.

Configure your integration

Step 1. Create an integration

1. If you haven't already created an integration, follow the steps in Creating integrations to create a new integration.

2. In your integration's configuration on the Developer Portal, make sure to set the following scopes:

   • design:content: Read and Write
   • design:meta: Read
   • brandtemplate:meta: Read
   • brandtemplate:content: Read

After creating your integration, you should have the following details for your integration:

• Your Client ID.
• Your Client secret.
• A list of your integration's scopes.
• At least one authorization redirect URL.

Step 2. Authenticate with OAuth

1. Follow the Authentication guide to get an authorization code, then generate an access token for your requests. For this process you need:

   • Your Client ID.
   • Your Client secret.
   • A URL-encoded list of your integration's scopes.
   • One of your nominated redirect URLs.

2. (Optional) If you've already authenticated but your token has expired, you can skip step 1 and request a new token using your refresh token.

When you've successfully authenticated and obtained a bearer token, you're ready to generate your autofilled design.

Generate an autofilled design

Step 0. (Optional) Get a list of all brand templates

If you don't know your brand template's ID, you can get a list of all brand templates.

Step 1. Query your brand template

Query your brand template's dataset to return a list of autofillable fields.

1. Request your template's dataset with a call to GET /brand-templates/{TEMPLATE-ID}/dataset.

   curl --request GET \
     --url https://api.canva.com/rest/v1/brand-templates/{TEMPLATE-ID}/dataset \
     --header 'Authorization: Bearer {TOKEN}'

   shell

   Copy

2. The endpoint returns the available fields and their data type in the dataset object.

   {
     "dataset": {
       "CITY": {
         "type": "text"
       },
       "TEMPERATURE": {
         "type": "text"
       },
       "BACKGROUND": {
         "type": "image"
       }
     }
   }

   json

   Copy

3. (Optional) Upload a new image.

   If your template accepts an image field, you can optionally upload a new asset.

Step 2. Create a design autofill job

Create your new design with an asynchronous design autofill request, including your autofill data in the body of the request.

1. Initiate your job with a call to POST /autofills.

   curl --request POST \
   --url https://api.canva.com/rest/v1/autofills \
   --header 'Authorization: Bearer {TOKEN}' \
   --header 'Content-Type: application/json' \
   --data '{
     "brand_template_id": "{TEMPLATE-ID}",
     "data": {
       "CITY": {
         "type": "text",
         "text": "Sydney"
       },
       "TEMPERATURE": {
         "type": "text",
         "text": "25C"
       },
       "BACKGROUND": {
         "type": "image",
         "asset_id": "{ASSET-ID}"
       }
     }
   }'

   shell

   Copy

2. The endpoint returns an autofill job with its ID and status.

   {
     "job": {
       "id": "a71ef223-571c-48a2-9572-e6cf85e3b943",
       "status": "in_progress"
     }
   }

   json

   Copy

   Save the ID so you can retrieve your design when the job is complete.

Step 3. Get your design autofill job

Jobs are generated asynchronously and might take some time to complete. Periodically poll the autofill job API with the job's ID until the design is ready.

1. Call GET /autofills/{JOB-ID}

   curl --request GET \
   --url https://api.canva.com/rest/v1/autofills/a71ef223-571c-48a2-9572-e6cf85e3b943 \
   --header 'Authorization: Bearer {TOKEN}'

   shell

   Copy

2. The endpoint returns the job's status. A successfully completed job has the status success and includes the design details in the response.

   {
     "job": {
       "id": "{ID}",
       "status": "success",
       "result": {
         "type": "create_design",
         "design": {
           "url": "https://www.canva.com/design/{DESIGN-ID}/edit",
           "thumbnail": {
             "url": "https://export-download.canva.com/{THUMBNAIL-RESOURCE}"
           }
         }
       }
     }
   }

   json

   Copy

   Direct your user to the design's URL so they can open it in the Canva editor and adjust or export it as required.