> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# Create design import job

Create an asynchronous job to import a design created in another application.

Starts a new [asynchronous job](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints) to import an external file as a new design in Canva.

The request format for this endpoint has an `application/octet-stream` body of bytes,
and the information about the import is provided using an `Import-Metadata` header.

Supported file types for imports are listed in [Design imports overview](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/#supported-file-types).

<Note>
  For more information on the workflow for using asynchronous jobs, see [API requests and responses](https://www.canva.dev/docs/apps/rest-apis/requests-responses/#asynchronous-job-endpoints). You can check the status and get the results of design import jobs created with this API using the [Get design import job API](https://www.canva.dev/docs/apps/rest-apis/reference/design-imports/get-design-import-job/).
</Note>

## HTTP method and URL path

POST https\://api.canva.com/rest/v1/imports

This operation is rate limited to 20 requests per minute for each user of your app.

## Authentication and authorization

This endpoint requires a valid access token that acts on behalf of a user. For more information, see [Generate an access token](/docs/apps/rest-apis/reference/authentication/generate-access-token).

### Scopes

The access token must have all the following [scopes](/docs/apps/rest-apis/scopes) (permissions):

* `design:content:write`

## Header parameters

<Prop.List>
  <Prop name="Authorization" type="string" required>
    Provides credentials to authenticate the request, in the form of a `Bearer` token.

    For example: `Authorization: Bearer {token}`
  </Prop>

  <Prop name="Content-Type" type="string" required>
    Indicates the media type of the information sent in the request. This must be set to `application/octet-stream`.

    For example: `Content-Type: application/octet-stream`
  </Prop>

  <Prop name="Import-Metadata" type="DesignImportMetadata" required>
    Metadata about the design that you include as a header parameter when importing a design.

    <PillAccordion title={<>Properties of <strong>Import-Metadata</strong></>}>
      <Prop.List>
        <Prop name="title_base64" type="string" required>
          The design's title, encoded in Base64.

          The maximum length of a design title in Canva (unencoded) is 50 characters.

          Base64 encoding allows titles containing emojis and other special
          characters to be sent using HTTP headers.
          For example, "My Awesome Design 😍" Base64 encoded
          is `TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==`.

          <Prop.Extras>
            **Minimum length:** `1`
          </Prop.Extras>
        </Prop>

        <Prop name="mime_type" type="string">
          The MIME type of the file being imported. If not provided, Canva attempts to automatically detect the type of the file.
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Body parameters

Binary of the file to import.

## Example request

Examples for using the `/v1/imports` endpoint:

<Tabs storageKey="example.language" disableContentTransition>
  <Tab name="cURL">
    ```sh
    curl --request POST 'https://api.canva.com/rest/v1/imports' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/octet-stream' \
    --header 'Import-Metadata: { "title_base64": "TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==", "mime_type": "application/pdf" }' \
    --data-binary '@/path/to/file'
    ```
  </Tab>

  <Tab name="Node.js">
    ```js
    const fetch = require("node-fetch");
    const fs = require("fs");

    fetch("https://api.canva.com/rest/v1/imports", {
      method: "POST",
      headers: {
        "Authorization": "Bearer {token}",
        "Content-Length": fs.statSync("/path/to/file").size,
        "Content-Type": "application/octet-stream",
        "Import-Metadata": JSON.stringify({ "title_base64": "TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==", "mime_type": "application/pdf" }),
      },
      body: fs.createReadStream("/path/to/file"),
    })
      .then(async (response) => {
        const data = await response.json();
        console.log(data);
      })
      .catch(err => console.error(err));
    ```
  </Tab>

  <Tab name="Java">
    ```java
    import java.io.IOException;
    import java.net.URI;
    import java.net.http.*;
    import java.nio.file.Paths;

    public class ApiExample {
        public static void main(String[] args) throws IOException, InterruptedException {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.canva.com/rest/v1/imports"))
                .header("Authorization", "Bearer {token}")
                .header("Content-Type", "application/octet-stream")
                .header("Import-Metadata", "{ \"title_base64\": \"TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==\", \"mime_type\": \"application/pdf\" }")
                .method("POST", HttpRequest.BodyPublishers.ofFile(Paths.get("/path/to/file")))
                .build();

            HttpResponse<String> response = HttpClient.newHttpClient().send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );
            System.out.println(response.body());
        }
    }
    ```
  </Tab>

  <Tab name="Python">
    ```py
    import requests
    import json

    headers = {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/octet-stream",
        "Import-Metadata": json.dumps({ "title_base64": "TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==", "mime_type": "application/pdf" })
    }

    with open("/path/to/file", "rb") as file:
        response = requests.post("https://api.canva.com/rest/v1/imports",
            headers=headers,
            data=file
        )
        print(response.json())
    ```
  </Tab>

  <Tab name="C#">
    ```csharp
    using System.Net.Http;
    using System.Net.Http.Headers;

    var client = new HttpClient();
    var request = new HttpRequestMessage
    {
      Method = HttpMethod.Post,
      RequestUri = new Uri("https://api.canva.com/rest/v1/imports"),
      Headers =
      {
        { "Authorization", "Bearer {token}" },
        { "Import-Metadata", "{ \"title_base64\": \"TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==\", \"mime_type\": \"application/pdf\" }" },
      },
      Content = new StreamContent(File.OpenRead("/path/to/file"))
      {
        Headers =
        {
          ContentType = new MediaTypeHeaderValue("application/octet-stream"),
        }
      },
    };

    using (var response = await client.SendAsync(request))
    {
      response.EnsureSuccessStatusCode();
      var body = await response.Content.ReadAsStringAsync();
      Console.WriteLine(body);
    };
    ```
  </Tab>

  <Tab name="Go">
    ```go
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    	"os"
    )

    func main() {
    	payload, _ := os.Open("/path/to/file")
    	defer payload.Close()

    	url := "https://api.canva.com/rest/v1/imports"
    	req, _ := http.NewRequest("POST", url, payload)
    	req.Header.Add("Authorization", "Bearer {token}")
    	req.Header.Add("Content-Type", "application/octet-stream")
    	req.Header.Add("Import-Metadata", "{ \"title_base64\": \"TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==\", \"mime_type\": \"application/pdf\" }")

    	res, _ := http.DefaultClient.Do(req)
    	defer res.Body.Close()
    	body, _ := io.ReadAll(res.Body)
    	fmt.Println(string(body))
    }
    ```
  </Tab>

  <Tab name="PHP">
    ```php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.canva.com/rest/v1/imports",
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer {token}',
        'Content-Type: application/octet-stream',
        'Import-Metadata: { "title_base64": "TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==", "mime_type": "application/pdf" }',
      ),
      CURLOPT_POSTFIELDS => file_get_contents("/path/to/file")
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if (empty($err)) {
      echo $response;
    } else {
      echo "Error: " . $err;
    }
    ```
  </Tab>

  <Tab name="Ruby">
    ```ruby
    require 'net/http'
    require 'uri'

    url = URI('https://api.canva.com/rest/v1/imports')
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(url)
    request['Authorization'] = 'Bearer {token}'
    request['Content-Type'] = 'application/octet-stream'
    request['Import-Metadata'] = '{ "title_base64": "TXkgQXdlc29tZSBEZXNpZ24g8J+YjQ==", "mime_type": "application/pdf" }'
    request.body = File.read('/path/to/file')

    response = http.request(request)
    puts response.read_body
    ```
  </Tab>
</Tabs>

## Success response

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

<Prop.List>
  <Prop name="job" type="DesignImportJob" required mode="output">
    The status of the design import job.

    <PillAccordion title={<>Properties of <strong>job</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="id" type="string" required mode="output">
          The ID of the design import job.
        </Prop>

        <Prop name="status" type="string" required mode="output">
          The status of the design import job.

          <Prop.Extras>
            **Available values:**

            * `failed`
            * `in_progress`
            * `success`
          </Prop.Extras>
        </Prop>

        <Prop name="result" type="DesignImportJobResult" mode="output">
          <PillAccordion title={<>Properties of <strong>result</strong></>}>
            <Prop.List>
              <Prop name="designs" type="DesignSummary[]" required mode="output">
                A list of designs imported from the external file. It usually contains one item.
                Imports with a large number of pages or assets are split into multiple designs.

                <PillAccordion title={<>Properties of <strong>designs</strong></>}>
                  <Prop.List>
                    <Prop name="id" type="string" required mode="output">
                      The design ID.
                    </Prop>

                    <Prop name="urls" type="DesignLinks" required mode="output">
                      A temporary set of URLs for viewing or editing the design.

                      <PillAccordion title={<>Properties of <strong>urls</strong></>}>
                        <Prop.List>
                          <Prop name="edit_url" type="string" required mode="output">
                            A temporary editing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows.

                            NOTE: This is not a permanent URL, it is only valid for 30 days.
                          </Prop>

                          <Prop name="view_url" type="string" required mode="output">
                            A temporary viewing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows.

                            NOTE: This is not a permanent URL, it is only valid for 30 days.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="created_at" type="integer" required mode="output">
                      When the design was created in Canva, as a Unix timestamp (in seconds since the Unix
                      Epoch).
                    </Prop>

                    <Prop name="updated_at" type="integer" required mode="output">
                      When the design was last updated in Canva, as a Unix timestamp (in seconds since the
                      Unix Epoch).
                    </Prop>

                    <Prop name="title" type="string" mode="output">
                      The design title.
                    </Prop>

                    <Prop name="url" type="string" mode="output">
                      URL of the design.
                    </Prop>

                    <Prop name="thumbnail" type="Thumbnail" mode="output">
                      A thumbnail image representing the object.

                      <PillAccordion title={<>Properties of <strong>thumbnail</strong></>}>
                        <Prop.List>
                          <Prop name="width" type="integer" required mode="output">
                            The width of the thumbnail image in pixels.
                          </Prop>

                          <Prop name="height" type="integer" required mode="output">
                            The height of the thumbnail image in pixels.
                          </Prop>

                          <Prop name="url" type="string" required mode="output">
                            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.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="page_count" type="integer" mode="output">
                      The total number of pages in the design. Some design types don't have pages (for example, Canva docs).
                    </Prop>
                  </Prop.List>
                </PillAccordion>
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>

        <Prop name="error" type="DesignImportError" mode="output">
          If the import job fails, this object provides details about the error.

          <PillAccordion title={<>Properties of <strong>error</strong></>}>
            <Prop.List>
              <Prop name="code" type="string" required mode="output">
                A short string about why the import failed. This field can be used to handle errors
                programmatically.

                <Prop.Extras>
                  **Available values:**

                  * `design_creation_throttled`
                  * `design_import_throttled`
                  * `duplicate_import`
                  * `internal_error`
                  * `invalid_file`
                  * `fetch_failed`
                </Prop.Extras>
              </Prop>

              <Prop name="message" type="string" required mode="output">
                A human-readable description of what went wrong.
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Example responses

### In progress job

```json
{
  "job": {
    "id": "e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8",
    "status": "in_progress"
  }
}
```

### Successfully completed job

```json
{
  "job": {
    "id": "e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8",
    "status": "success",
    "result": {
      "designs": [
        {
          "id": "DAGQm2AkzOk",
          "title": "My Awesome Design",
          "thumbnail": {
            "width": 376,
            "height": 531,
            "url": "https://document-export.canva.com/..."
          },
          "urls": {
            "edit_url": "https://www.canva.com/api/design/...",
            "view_url": "https://www.canva.com/api/design/..."
          },
          "created_at": 1726198998,
          "updated_at": 1726199000
        }
      ]
    }
  }
}
```

### Failed job

```json
{
  "job": {
    "id": "e08861ae-3b29-45db-8dc1-1fe0bf7f1cc8",
    "status": "failed",
    "error": {
      "code": "invalid_file",
      "message": "Document could not be imported because the file is corrupt."
    }
  }
}
```