---
title: "Quickstart Guide"
description: "A typical implementation flow for the CloudConvert API"
canonical_url: "https://cloudconvert.com/docs/getting-started/quickstart-guide"
---
# Quickstart Guide

> A typical implementation flow for the CloudConvert API

## Quickstart Guide

This guide walks you through a typical implementation of the CloudConvert API. It
covers creating a job, waiting for it to finish, and handling the result. Use this
quickstart guide as an entry point. For more in-depth documentation, use the menu on
the left to jump directly to a specific topic.

You can find example requests and SDK code examples below.

---

## Starting Jobs

The following example shows how to [create](https://cloudconvert.com/docs/raw/api-reference/jobs.md#create-job) a typical
job. It downloads a file from a URL (`import/url` operation), converts the file to
PDF, and creates a download URL for the converted file (`export/url` operation).

If you are using a storage provider such as S3, Azure, Google Cloud, or OpenStack, we
recommend using the corresponding import and export operations. CloudConvert can
fetch files from your storage and store converted files there.

Depending on the input and output format, the available options for the `convert`
operation vary. You can use the [Job Builder](https://cloudconvert.com/job-builder)
to generate the payload for your job. It shows all available operations and options.

#### Raw HTTP Request

<api-endpoint endpoint="jobs" method="POST">

[https://api.cloudconvert.com/v2/jobs](https://api.cloudconvert.com/v2/jobs)

</api-endpoint>

#### Request Body

```json
{
  "tasks": {
    "import-my-file": {
      "operation": "import/url",
      "url": "https://my.url/file.docx"
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "output_format": "pdf"
    },
    "export-my-file": {
      "operation": "export/url",
      "input": "convert-my-file"
    }
  }
}
```

#### Example Response

```json
{
  "data": {
    "id": "6559c281-ed85-4728-80db-414561c631e9",
    "status": "processing",
    "tasks": [
      ...
    ]
  }
}
```

#### SDK Examples

<code-group>

```php [PHP]
// composer require cloudconvert/cloudconvert-php

use \CloudConvert\CloudConvert;
use \CloudConvert\Models\Job;
use \CloudConvert\Models\Task;

$cloudconvert = new CloudConvert([
    'api_key' => 'API_KEY',
    'sandbox' => false
]);

$job = (new Job())
    ->addTask(
        (new Task('import/url', 'import-my-file'))
            ->set('url', 'https://my.url/file.docx')
    )
    ->addTask(
        (new Task('convert', 'convert-my-file'))
            ->set('input', 'import-my-file')
            ->set('output_format', 'pdf')
    )
    ->addTask(
        (new Task('export/url', 'export-my-file'))
            ->set('input', 'convert-my-file')
    );

$cloudconvert->jobs()->create($job);
```

```js [node.js]
// npm install --save cloudconvert

import CloudConvert from 'cloudconvert';

const cloudConvert = new CloudConvert('API_KEY');

let job = await cloudConvert.jobs.create({
    "tasks": {
        "import-my-file": {
            "operation": "import/url",
            "url": "https://my.url/file.docx"
        },
        "convert-my-file": {
            "operation": "convert",
            "input": "import-my-file",
            "output_format": "pdf"
        },
        "export-my-file": {
            "operation": "export/url",
            "input": "convert-my-file"
        }
    }
});
```

```python [Python]
# pip install cloudconvert

import cloudconvert

cloudconvert.configure(api_key='API_KEY', sandbox=False)

job = cloudconvert.Job.create(payload={
    "tasks": {
        'import-my-file': {
            'operation': 'import/url',
            'url': 'https://my-url'
        },
        'convert-my-file': {
            'operation': 'convert',
            'input': 'import-my-file',
            'output_format': 'pdf',
            'some_other_option': 'value'
        },
        'export-my-file': {
            'operation': 'export/url',
            'input': 'convert-my-file'
        }
    }
})
```

```ruby [Ruby]
# Add to your Gemfile: gem "cloudconvert"

cloudconvert = CloudConvert::Client.new(api_key: "API_KEY", sandbox: false)

job = cloudconvert.jobs.create(
  tasks: [
    {
      name: "import-my-file",
      operation: "import/url",
      url: "https://my-url"
    },
    {
      name: "convert-my-file",
      operation: "convert",
      input: "import-my-file",
      output_format: "pdf",
      some_other_option: "value"
    },
    {
      name: "export-my-file",
      operation: "export/url",
      input: "convert-my-file"
    }
  ]
)
```

```java [Java]
import com.cloudconvert.client.CloudConvertClient;
import com.cloudconvert.client.setttings.StringSettingsProvider;
import com.cloudconvert.dto.request.JobRequest;
import com.cloudconvert.dto.request.TaskRequest;
import com.cloudconvert.dto.request.ConvertFilesTaskRequest;
import com.cloudconvert.dto.request.UrlImportRequest;
import com.cloudconvert.dto.request.UrlExportRequest;
import com.cloudconvert.dto.response.JobResponse;
import com.google.common.collect.ImmutableMap;

final CloudConvertClient cloudConvertClient =
    new CloudConvertClient(new StringSettingsProvider("API_KEY", "WEBHOOK_SIGNING_SECRET"));

final JobResponse createJobResponse = cloudConvertClient.jobs().create(
    ImmutableMap.of(
        "import-my-file",
            new UrlImportRequest()
                .setUrl("import-url"),
        "convert-my-file",
            new ConvertFilesTaskRequest()
                .setInput("import-my-file")
                .setOutputFormat("pdf"),
        "export-my-file",
            new UrlExportRequest()
                .setInput("convert-my-file")
    )
).getBody();
```

```csharp [.NET]
// dotnet add package CloudConvert.API

using CloudConvert.API;
using CloudConvert.API.Models.ExportOperations;
using CloudConvert.API.Models.ImportOperations;
using CloudConvert.API.Models.JobModels;
using CloudConvert.API.Models.TaskOperations;

var CloudConvert = new CloudConvertAPI("API_KEY");

var job = await CloudConvert.CreateJobAsync(new JobCreateRequest
{
    Tasks = new
    {
        import_it = new ImportUrlCreateRequest
        {
            Url = "https://my.url/file.docx"
        },
        convert = new ConvertCreateRequest
        {
            Input = "import_it",
            Input_Format = "docx",
            Output_Format = "pdf"
        },
        export_it = new ExportUrlCreateRequest
        {
            Input = "convert"
        }
    }
});
```

</code-group>

---

## Waiting for Job Completion

We recommend using [webhooks](https://cloudconvert.com/docs/raw/api-reference/webhooks.md) to be
notified when a job completes.
Alternatively, you can use the [synchronous API endpoint](https://cloudconvert.com/docs/raw/api-reference/jobs.md#wait-for-job)`GET /v2/jobs/{id}` to wait for job completion.

#### Raw HTTP Request

<api-endpoint endpoint="jobs/6559c281-ed85-4728-80db-414561c631e9" method="GET" :sync="true">

[https://api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9](https://api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9)

</api-endpoint>

#### Example Response

```json
{
  "data": {
    "id": "6559c281-ed85-4728-80db-414561c631e9",
    "status": "finished",
    "tasks": [
      {
        "id": "7f110c42-3245-41cf-8555-37087c729ed2",
        "name": "import-my-file",
        "operation": "import/url",
        "status": "finished"
      },
      {
        "id": "7a142bd0-fa20-493e-abf5-99cc9b5fd7e9",
        "name": "convert-my-file",
        "operation": "convert",
        "status": "finished"
      },
      {
        "id": "36af6f54-1c01-45cc-bcc3-97dd23d2f93d",
        "name": "export-my-file",
        "operation": "export/url",
        "status": "finished",
        "result": {
          "files": [
            {
              "filename": "file.pdf",
              "url": "https://storage.cloudconvert.com/eed87242-577e-4e3e-8178-9edbe51975dd/file.pdf?temp_url_sig=79c2db4d884926bbcc5476d01b4922a19137aee9&temp_url_expires=1545962104"
            }
          ]
        }
      }
    ]
  }
}
```

#### SDK Examples

<code-group>

```php [PHP]
$cloudconvert->jobs()->wait($job);
```

```js [node.js]
job = await cloudConvert.jobs.wait(job.id);
```

```python [Python]
job = cloudconvert.Job.wait(id=job['id'])
```

```ruby [Ruby]
job = cloudconvert.jobs.wait(job.id)
```

```java [Java]
final JobResponse waitJobResponse =
    cloudConvertClient.jobs().wait(createJobResponse.getId()).getBody();
```

```csharp [.NET]
var job = await CloudConvertAPI.WaitJobAsync(job.Data.Id); // Wait for job completion
```

</code-group>

---

## Downloading Output Files

This example uses the `export/url` operation to generate a download URL for the
output file. You can find this URL in the response from the `/jobs/{ID}` status
endpoint or in the body of the [webhook](https://cloudconvert.com/docs/raw/api-reference/webhooks.md) payload.
Add the `?redirect=true` query parameter to the [status endpoint](https://cloudconvert.com/docs/raw/api-reference/jobs.md#show-job)
to be redirected to the export URL. Export URLs are valid for only 24 hours.

If you are using an export method such as S3 or
Azure, you do not need to manually download the output files.

#### Raw HTTP Request

<api-endpoint endpoint="jobs/6559c281-ed85-4728-80db-414561c631e9?redirect=true" method="GET">

[https://api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9?redirect=true](https://api.cloudconvert.com/v2/jobs/6559c281-ed85-4728-80db-414561c631e9?redirect=true)

</api-endpoint>

#### SDK Examples

<code-group>

```php [PHP]
$file = $job->getExportUrls()[0];

$source = $cloudconvert->getHttpTransport()->download($file->url)->detach();
$dest = fopen('output/' . $file->filename, 'w');

stream_copy_to_stream($source, $dest);
```

```js [node.js]
const file = cloudconvert.jobs.getExportUrls(job)[0];

const writeStream = fs.createWriteStream('./out/' + file.filename);

http.get(file.url, function(response) {
    response.pipe(writeStream);
});

await new Promise((resolve, reject) => {
    writeStream.on('finish', resolve);
    writeStream.on('error', reject);
});
```

```python [Python]
for task in job["tasks"]:
    if task.get("name") == "export-my-file" and task.get("status") == "finished":
        export_task = task

file = export_task.get("result").get("files")[0]
cloudconvert.download(filename=file['filename'], url=file['url'])
```

```ruby [Ruby]
export_task = job.tasks.where(operation: "export/url").where(status: "finished").first

file = export_task.result.files.first

cloudconvert.download(file.url, destination: "/path/to/destination")
```

```java [Java]
// Get the export/url task ID
final TaskResponse exportUrlTask =
    waitJobResponse.getTasks().stream().filter(
         taskResponse -> taskResponse.getName().equals("export-my-file")
    ).findFirst().get();

// Get the URL of the export/url task
final String exportUrl =
    exportUrlTask
        .getResult()
        .getFiles()
        .get(0)
        .get("url");

// Get the file as an input stream using the export/url task URL
final InputStream inputStream =
    cloudConvertClient.files().download(exportUrl).getBody();
```

```csharp [.NET]
var exportTask = job.Data.Tasks.FirstOrDefault(t => t.Name == "export_it");

var fileExport = exportTask.Result.Files.FirstOrDefault();

using (var client = new WebClient()) client.DownloadFile(fileExport.Url, fileExport.Filename);
```

</code-group>


## Sitemap

See the full [sitemap](https://cloudconvert.com/docs/sitemap.md) for all pages.