import { requestDataFieldMatching } from "@canva/design";
import type { DataFieldMatchingOptions } from "@canva/design";

const opts: DataFieldMatchingOptions = {
  sampleData: {
    columnConfigs: [
      { name: 'Listing title', type: 'string' },
      { name: 'Price', type: 'number' },
      { name: 'Bedrooms', type: 'number' },
    ],
    rows: [
      {
        cells: [
          { type: 'string', value: 'Modern apartment near the beach' },
          { type: 'number', value: 850000 },
          { type: 'number', value: 2 },
        ],
      },
    ],
  },
};

const response = await requestDataFieldMatching(opts);

if (response.status === 'success') {
  // The matching request completed without an error.
}

TYPESCRIPT

Parameters

optsDataFieldMatchingOptions

Required

The configuration options for this data field matching request.

sampleDataDataTable

Required

Structured tabular data for import into Canva. Mirrors the public DataTable but with the Beta DataTableRow (whose media cells may contain references to already-imported media).

Example: Creating a data table

import type { ColumnConfig, DataTableCell, DataTable, DataTableRow } from '@canva/intents/data';

const myTable: DataTable = {
  columnConfigs: [
    { name: 'Name', type: 'string' },
    { name: 'Age', type: 'number' },
    { name: 'Subscribed', type: 'boolean' },
    { name: 'Join Date', type: 'date' }
  ],
  rows: [
    {
      cells: [
        { type: 'string', value: 'Alice' },
        { type: 'number', value: 30 },
        { type: 'boolean', value: true },
        { type: 'date', value: Math.floor(new Date('2023-01-15').getTime() / 1000) }
      ]
    },
    {
      cells: [
        { type: 'string', value: 'Bob' },
        { type: 'number', value: 24 },
        { type: 'boolean', value: false },
        { type: 'date', value: Math.floor(new Date('2022-07-20').getTime() / 1000) }
      ]
    }
  ]
};

rowsDataTableRow[]

Required

The data rows containing the actual values.

cellsDataTableCell<DataType>[]

Required

Array of cells containing the data values.

Cell containing a date value.

Example: Creating a date cell

import type { DateDataTableCell } from '@canva/intents/data';

const todayCell: DateDataTableCell = {
  type: 'date',
  value: Math.floor(Date.now() / 1000) // Unix timestamp in seconds
};

const emptyDateCell: DateDataTableCell = {
  type: 'date',
  value: undefined
};

typestring

Required

Indicates this cell contains a date value.

The only valid value is "date".

valuenumber | undefined

Required

Unix timestamp in seconds representing the date.

Use undefined for an empty cell.

Cell containing a text value.

Example: Creating a string cell

import type { StringDataTableCell } from '@canva/intents/data';

const nameCell: StringDataTableCell = {
  type: 'string',
  value: 'John Doe'
};

const emptyStringCell: StringDataTableCell = {
  type: 'string',
  value: undefined
};

typestring

Required

Indicates this cell contains a string value.

The only valid value is "string".

valuestring | undefined

Required

Text content of the cell.

Maximum length: 10,000 characters

Use undefined for an empty cell.

Cell containing a numeric value.

Example: Creating a number cell

import type { NumberCellMetadata, NumberDataTableCell } from '@canva/intents/data';

const priceCell: NumberDataTableCell = {
  type: 'number',
  value: 29.99,
  metadata: { formatting: '[$$]#,##0.00' }
};

const quantityCell: NumberDataTableCell = {
  type: 'number',
  value: 150
};

const emptyNumberCell: NumberDataTableCell = {
  type: 'number',
  value: undefined
};

typestring

Required

Indicates this cell contains a number value.

The only valid value is "number".

valuenumber | undefined

Required

Numeric value within safe integer range.

Valid range: Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER

Invalid values:

Infinity or -Infinity
NaN
Negative zero (-0)
Denormalized numbers

Use undefined for an empty cell.

metadataNumberCellMetadata

Optional

Optional formatting information for displaying the number.

Example: Applying display formatting to a number

import type { NumberCellMetadata } from '@canva/intents/data';

const currencyFormatting: NumberCellMetadata = { formatting: '[$USD]#,##0.00' };
const percentageFormatting: NumberCellMetadata = { formatting: '0.00%' };

formattingstring

Optional

Formatting pattern using Office Open XML Format.

These patterns control how numbers are displayed to users, including currency symbols, decimal places, and separators.

Cell containing a boolean value.

Examples

Creating a boolean cell

import type { BooleanDataTableCell } from '@canva/intents/data';

const isActiveCell: BooleanDataTableCell = {
  type: 'boolean',
  value: true
};

Creating a boolean cell with false value

import type { BooleanDataTableCell } from '@canva/intents/data';

const isCompleteCell: BooleanDataTableCell = {
  type: 'boolean',
  value: false
};

Creating an empty boolean cell

import type { BooleanDataTableCell } from '@canva/intents/data';

const emptyBooleanCell: BooleanDataTableCell = {
  type: 'boolean',
  value: undefined
};

typestring

Required

Indicates this cell contains a boolean value.

The only valid value is "boolean".

valueboolean | undefined

Required

Boolean value (true or false).

Use undefined for an empty cell.

Cell containing a media collection. In the Preview (Beta) API this additionally accepts references to already-imported Canva media (image_reference / video_reference).

Examples

Creating a media cell with an image

import type { MediaCollectionDataTableCell } from '@canva/intents/data';

const mediaCell: MediaCollectionDataTableCell = {
  type: 'media',
  value: [{
    type: 'image_upload',
    url: 'https://www.canva.dev/example-assets/image-import/image.jpg',
    mimeType: 'image/jpeg',
    thumbnailUrl: 'https://www.canva.dev/example-assets/image-import/thumbnail.jpg',
    aiDisclosure: 'none'
  }]
};

Creating an empty media cell

import type { MediaCollectionDataTableCell } from '@canva/intents/data';

const emptyMediaCell: MediaCollectionDataTableCell = {
  type: 'media',
  value: []
};

typestring

Required

Indicates this cell contains a media collection.

The only valid value is "media".

valueobject[]

Required

Media collection values. Use an empty array for an empty cell.

Options for uploading an image asset to the user's private media library.

typestring

Required

Indicates this value contains options for image uploading.

The only valid value is "image_upload".

urlstring

Required

The URL of the image file to upload. This can be an external URL or a data URL.

Requirements for external URLs:

Must use HTTPS
Must return a 200 status code
Content-Type must match the file's MIME type
Must be publicly accessible (i.e. not a localhost URL)
Must not redirect
Must not contain an IP address
Maximum length: 4096 characters
Must not contain whitespace
Must not contain these characters: >, <, {, }, ^, backticks
Maximum file size: 50MB

Requirements for data URLs:

Must include ;base64 for base64-encoded data
Maximum size: 10MB (10 × 1024 × 1024 characters)

Requirements for SVGs:

Disallowed elements:
- a
- altglyph
- altglyphdef
- altglyphitem
- animate
- animatemotion
- animatetransform
- cursor
- discard
- font
- font-face
- font-face-format
- font-face-name
- font-face-src
- font-face-uri
- foreignobject
- glyph
- glyphref
- missing-glyph
- mpath
- script
- set
- switch
- tref
Disallowed attributes:
- crossorigin
- lang
- media
- onload
- ping
- referrerpolicy
- rel
- rendering-intent
- requiredextensions
- requiredfeatures
- systemlanguage
- tabindex
- transform-origin
- unicode
- vector-effect
The href attribute of an image element only supports data URLs for PNG and JPEG images.
The URL in the href attribute must not point to a location outside of the SVG.
The style attribute must not use the mix-blend-mode property.

mimeTypeImageMimeType

Required

The MIME type of the image file.

Available values:

"image/jpeg"
"image/heic"
"image/png"
"image/svg+xml"
"image/webp"
"image/tiff"

thumbnailUrlstring

Required

The URL of a thumbnail image to display while the image is queued for upload. This can be an external URL or a data URL.

Requirements for external URLs:

Must use HTTPS
Must support Cross-Origin Resource Sharing
Must be a PNG, JPEG, or SVG file
Maximum length: 4096 characters

Requirements for data URLs:

Must include ;base64 for base64-encoded data
Maximum size: 10MB (10 × 1024 × 1024 characters)

aiDisclosureAiDisclosure

Required

A disclosure identifying if the app generated this image using AI

Helps users make informed decisions about the content they interact with. See AiDisclosure for the full definition.

App Generated

'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when the app requests a third-party service to take similar action on an image using AI.

Required for the following cases (this list is not exhaustive):

Case	Reason
AI generates a new image from scratch	Creates new creative content
AI changes the style of the image e.g. makes it cartoon	Significantly alters the style
AI removes an object and replaces it with new content	Creates new creative content
AI changes the facial expression of a person in an image	Can alter content's original meaning
AI composites multiple images together	Significantly alters context
AI expands an image by generating new content to fill the edges	Creates new creative content
AI replaces background by generating new content	Creates new creative content

None

'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to third-party hosted content.

Required for the following cases (this list is not exhaustive):

Case	Reason
Asset comes from an asset library	Didn't generate the asset itself
AI corrects red eyes	A minor correction
AI removes background without replacement	Doesn't change original meaning by itself
AI changes the color of an object in an image	Doesn't change original meaning by itself
AI detects image defects and suggests manual fixes	Didn't change the asset itself
AI adjusts brightness and contrast on an image	Doesn't change original meaning by itself
AI upscales an image	Doesn't change original meaning by itself

Available values:

"app_generated"
"none"

namestring

Optional

A human-readable name for the image asset.

This name is displayed in the user's media library and helps users identify and find the asset later. If not provided, Canva will generate a name based on the asset's URL or a unique identifier.

Requirements:

Minimum length: 1 character (empty strings are not allowed)
Maximum length: 255 characters

Options for uploading a video asset to the user's private media library.

typestring

Required

Indicates this value contains options for video uploading.

The only valid value is "video_upload".

urlstring

Required

The URL of the video file to upload.

Requirements:

Must use HTTPS
Must return a 200 status code
Content-Type must match the file's MIME type
Must be publicly accessible (i.e. not a localhost URL)
Must not redirect
Must not contain an IP address
Maximum length: 4096 characters
Must not contain whitespace
Must not contain these characters: >, <, {, }, ^, backticks
Maximum file size: 1000MB (1GB)

mimeTypeVideoMimeType

Required

The MIME type of the video file.

Available values:

"video/avi"
"video/x-msvideo"
"image/gif"
"video/x-m4v"
"video/x-matroska"
"video/quicktime"
"video/mp4"
"video/mpeg"
"video/webm"
"application/json"

thumbnailImageUrlstring

Required

The URL of a thumbnail image to use as a fallback if thumbnailVideoUrl isn't provided. This can be an external URL or a data URL.

Requirements for external URLs:

Must use HTTPS
Must support Cross-Origin Resource Sharing
Must be a PNG, JPEG, or SVG file
Maximum length: 4096 characters

Requirements for data URLs:

Must include ;base64 for base64-encoded data
Maximum size: 10MB (10 × 1024 × 1024 characters)
The dimensions of the thumbnail must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched

aiDisclosureAiDisclosure

Required

A disclosure identifying if the app generated this video using AI.

Helps users make informed decisions about the content they interact with. See AiDisclosure for the full definition.

App Generated

'app_generated' indicates when the app creates or significantly alters an asset using AI. Includes when the app requests a third-party service to take similar action on a video using AI.

Required for the following cases (this list is not exhaustive):

Case	Reason
AI generates a new video from scratch	Creates new creative content
AI changes the style of the video e.g. makes it cartoon	Significantly alters the style
AI adds subtitles that rely on subjective interpretation	Creates new creative content
AI expands a video by generating new content to fill the edges	Creates new creative content
AI animates an image	Creates new creative content
AI fixes defects e.g. blur in a video by generating details	Creates new creative content
AI generates a talking head presenter	Creates new creative content

None

'none' indicates when the app doesn't create or significantly alter an asset using AI, or as a part of a request to third-party hosted content.

Required for the following cases (this list is not exhaustive):

Case	Reason
Asset comes from an asset library	Didn't generate the asset itself
AI corrects red eyes	A minor correction
AI adjusts brightness and contrast on a video	Doesn't change original meaning by itself
AI creates a slow motion effect in a video	Doesn't change original meaning by itself
AI adds AI word-by-word transcribed subtitles to a video	Doesn't change original meaning by itself

Available values:

"app_generated"
"none"

namestring

Optional

A human-readable name for the video asset.

This name is displayed in the user's media library and helps users identify and find the asset later. If not provided, Canva will generate a name based on the asset's URL or a unique identifier.

Requirements:

Minimum length: 1 character (empty strings are not allowed)
Maximum length: 255 characters

thumbnailVideoUrlstring

Optional

The URL of a thumbnail video to display while the video is queued for upload.

Requirements:

Must use HTTPS
Must support Cross-Origin Resource Sharing
Maximum length: 4096 characters
The dimensions of the thumbnail video must match the video's aspect ratio to prevent the thumbnail from appearing squashed or stretched
Must not be an AVI file. Although our APIs support uploading AVI videos, Canva can't preview them because of native support of browsers

A reference to an image already imported into the user's Canva media library. requestDataTable returns Data Connector media as references; pass them through unchanged to requestAutofillDesign or requestDataFieldMatching.

typestring

Required

Indicates this value references an already-imported image.

The only valid value is "image_reference".

refstring

Required

Opaque Canva media reference. Treat as a handle — do not construct or parse it.

A reference to a video already imported into the user's Canva media library. See DataTableImageReference.

typestring

Required

Indicates this value references an already-imported video.

The only valid value is "video_reference".

refstring

Required

Opaque Canva media reference. Treat as a handle — do not construct or parse it.

columnConfigsColumnConfig[]

Optional

Column definitions with names and data types.

namestring | undefined

Required

Name for the column, displayed as header text.

If undefined, the column will have no header text.

typeobject

Required

Expected data type for cells in this column.

Use a specific DataType for columns with consistent types, or 'variant' for columns that may contain mixed types.

Data types supported for table cells.

Available values:

"string"
"number"
"date"
"boolean"
"media"

The only valid value is "variant".

Returns

Response object from a data field matching request. This is a Promise that resolves with the following object:

statusstring

The only valid value is "success".