Skip navigation
Skip to main content
Autofill
Autofill

Create design autofill job

Create an asynchronous job to autofill a design from a brand template with your input information.

Starts a new job to autofill a Canva design using a brand template and input data.

To get a list of input data fields, use the Get brand template dataset API.

Available data field types to autofill include:

  • Images
  • Text
  • Charts

You can check the status and get the results of autofill jobs created with this API using the Get design autofill job API.

HTTP method and URL path

POST https://api.canva.com/rest/v1/autofills

This operation is rate limited to 10 requests per minute for each user of your integration.

Authentication

This endpoint requires a valid access token that acts on behalf of a user. The token must have the following scopes (permissions):

  • design:content:write

For more information, see Scopes.

Header parameters

#Authorizationstring
Required

Provides credentials to authenticate the request, in the form of a Bearer token.

For example: Authorization: Bearer {token}

#Content-Typestring
Required

Indicates the media type of the information sent in the request. This must be set to application/json.

For example: Content-Type: application/json

Body parameters

#brand_template_idstring
Required

ID of the input brand template.

#dataobject
Required

Data object containing the data fields and values to autofill.

Properties of data
#<KEY>object of DatasetValues
Required

The data field to autofill.

{
  "cute_pet_image_of_the_day": {
    "type": "image",
    "asset_id": "Msd59349ff"
  },
  "cute_pet_witty_pet_says": {
    "type": "text",
    "text": "It was like this when I got here!"
  },
  "cute_pet_sales_chart": {
    "type": "chart",
    "chart_data": {
      "rows": [
        {
          "cells": [
            {
              "type": "string",
              "value": "Geographic Region"
            },
            {
              "type": "string",
              "value": "Sales (millions AUD)"
            },
            {
              "type": "string",
              "value": "Target met?"
            },
            {
              "type": "string",
              "value": "Date met"
            }
          ]
        },
        {
          "cells": [
            {
              "type": "string",
              "value": "Asia Pacific"
            },
            {
              "type": "number",
              "value": 10.2
            },
            {
              "type": "boolean",
              "value": true
            },
            {
              "type": "date",
              "value": 1721944387
            }
          ]
        },
        {
          "cells": [
            {
              "type": "string",
              "value": "EMEA"
            },
            {
              "type": "number",
              "value": 13.8
            },
            {
              "type": "boolean",
              "value": false
            },
            {
              "type": "date"
            }
          ]
        }
      ]
    }
  }
}
json
#typestring
Required

This can be one of the following:

  • image: If the data field is an image field.

  • text: If the data field is a text field.

  • chart: If the data field is a chart.

#asset_idstring
Sometimes required

asset_id of the image to insert into the template element.

#textstring
Sometimes required

Text to insert into the template element.

#chart_dataDataTable
Sometimes required

Tabular data, structured in rows of cells.

  • The first row usually contains column headers.
  • Each cell must have a data type configured.
  • All rows must have the same number of cells.
  • Maximum of 100 rows and 20 columns.
Properties of chart_data
#rowsDataTableRow[]
Required

Rows of data.

The first row usually contains column headers. Maximum of 100 rows.

Properties of rows
#cellsDataTableCell[]
Required

Cells of data in row.

All rows must have the same number of cells. Maximum of 20 cells per row.

Properties of cells
#typestring
Required

This can be one of the following:

  • string: A string tabular data cell.

  • number: A number tabular data cell.

  • boolean: A boolean tabular data cell.

  • date: A date tabular data cell.

    Specified as a Unix timestamp (in seconds since the Unix Epoch).

#valuestring or number or boolean or date
Optional

The value of the cell. The data type of value depends on the type of the cell.

  • For a string type cell, the value is a string.
  • For a number type cell, the value is a number in Double format.
  • For a boolean type cell, the value is a boolean value (true or false).
  • For a date type cell, the value is an integer which is a Unix timestamp (in seconds since the Unix Epoch).

If a value is not provided, the cell is empty.

#titlestring
Optional

Title to use for the autofilled design. Must be less than 256 characters.

If no design title is provided, the autofilled design will have the same title as the brand template.

Example request

Examples for using the /v1/autofills endpoint:

curl --request POST 'https://api.canva.com/rest/v1/autofills' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
  "brand_template_id": "DAFVztcvd9z",
  "title": "string",
  "data": {
    "cute_pet_image_of_the_day": {
      "type": "image",
      "asset_id": "Msd59349ff"
    },
    "cute_pet_witty_pet_says": {
      "type": "text",
      "text": "It was like this when I got here!"
    },
    "cute_pet_sales_chart": {
      "type": "chart",
      "chart_data": {
        "rows": [
          {
            "cells": [
              {
                "type": "string",
                "value": "Geographic Region"
              },
              {
                "type": "string",
                "value": "Sales (millions AUD)"
              },
              {
                "type": "string",
                "value": "Target met?"
              },
              {
                "type": "string",
                "value": "Date met"
              }
            ]
          },
          {
            "cells": [
              {
                "type": "string",
                "value": "Asia Pacific"
              },
              {
                "type": "number",
                "value": 10.2
              },
              {
                "type": "boolean",
                "value": true
              },
              {
                "type": "date",
                "value": 1721944387
              }
            ]
          },
          {
            "cells": [
              {
                "type": "string",
                "value": "EMEA"
              },
              {
                "type": "number",
                "value": 13.8
              },
              {
                "type": "boolean",
                "value": false
              },
              {
                "type": "date"
              }
            ]
          }
        ]
      }
    }
  }
}'
sh

Success response

If successful, the endpoint returns a 200 response with a JSON body with the following parameters:

#jobDesignAutofillJob

Details about the autofill job.

Properties of job
#idstring

ID of the asynchronous job that is creating the design using the provided data.

#statusstring

Status of the design autofill job. This can be one of the following:

  • in_progress
  • success
  • failed
#resultDesignAutofillJobResult
Optional

Result of the design autofill job. Only present if job status is success.

Properties of result
#typestring

This can be one of the following:

  • create_design: Design has been created and saved to user's root folder.
#designDesignSummary

Basic details about the design, such as the design's ID, title, and URL.

Properties of design
#idstring

The design ID.

#urlsDesignLinks

A temporary set of URLs for viewing or editing the design.

Properties of urls
#edit_urlstring

A temporary editing URL for the design.

#view_urlstring

A temporary viewing URL for the design.

#created_atinteger

When the design was created in Canva, as a Unix timestamp (in seconds since the Unix Epoch).

#updated_atinteger

When the design was last updated in Canva, as a Unix timestamp (in seconds since the Unix Epoch).

#titlestring
Optional

The design title.

#urlstring
Optional

URL of the design.

#thumbnailThumbnail
Optional

A thumbnail image representing the object.

Properties of thumbnail
#widthinteger

The width of the thumbnail image in pixels.

#heightinteger

The height of the thumbnail image in pixels.

#urlstring

A URL for retrieving the thumbnail image. This URL expires after 15 minutes. This URL includes a query string that's required for retrieving the thumbnail.

#page_countinteger
Optional

The total number of pages in the design. Some design types don't have pages (for example, Canva docs).

#errorAutofillError
Optional

If the autofill job fails, this object provides details about the error.

Properties of error
#codestring

This can be one of the following:

  • autofill_error
  • thumbnail_generation_error
  • create_design_error
#messagestring

A human-readable description of what went wrong.

Example responses

In progress job

{
  "job": {
    "id": "450a76e7-f96f-43ae-9c37-0e1ce492ac72",
    "status": "in_progress"
  }
}
json

Successfully completed job

{
  "job": {
    "id": "450a76e7-f96f-43ae-9c37-0e1ce492ac72",
    "status": "success",
    "result": {
      "type": "create_design",
      "design": {
        "id": "DAFVztcvd9z",
        "title": "My summer holiday",
        "url": "https://www.canva.com/design/DAFVztcvd9z/edit",
        "thumbnail": {
          "width": 595,
          "height": 335,
          "url": "https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>"
        }
      }
    }
  }
}
json

Failed job

{
  "job": {
    "id": "450a76e7-f96f-43ae-9c37-0e1ce492ac72",
    "status": "failed",
    "error": {
      "code": "autofill_error",
      "message": "Error autofilling design from brand template"
    }
  }
}
json

Try it out

Step 1: Enter your access token

To get started, generate an access token or provide your own below