> For the complete documentation index, see [llms.txt](https://docs.atomyx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.atomyx.io/atomyx-submit/implementation/api-integration/creating-jobs.md).

# Creating Jobs

The main Submit API action is creating a job.

Use this endpoint when an external system needs to create a new Submit job and receive an upload URL for the end user.

```http
POST /jobs
```

When a job is created successfully, the API returns:

```http
201 Created
```

### Required field

The only required field in the current request schema is:

| Field        | Description                                                         |
| ------------ | ------------------------------------------------------------------- |
| `externalId` | An ID from the external system that can be used to identify the job |

The `externalId` is usually an order ID, job ID, quote ID, basket ID, or another identifier from the system creating the Submit job.

### Optional fields

You can also provide:

| Field          | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `callbackURL`  | A publicly accessible URL called when the job status changes           |
| `returnURL`    | A URL to redirect the end user to after they approve or reject artwork |
| `metadata`     | Informational properties displayed to the end user                     |
| `capabilities` | Controls which Submit UI features are enabled                          |
| `brand`        | Branding applied to the Submit UI                                      |
| `artwork`      | A publicly accessible artwork URL to process immediately               |

### Basic example

```json
{
  "externalId": "TEST-ORDER-10001"
}
```

### Example with metadata and return URL

```json
{
  "externalId": "TEST-ORDER-10001",
  "returnURL": "https://example.com/order/TEST-ORDER-10001/complete",
  "metadata": [
    {
      "propertyId": "orderNumber",
      "propertyName": "Order number",
      "value": "TEST-ORDER-10001"
    },
    {
      "propertyId": "customerName",
      "propertyName": "Customer name",
      "value": "Example Customer"
    }
  ]
}
```

### Example with capabilities

```json
{
  "externalId": "TEST-ORDER-10001",
  "capabilities": {
    "adjust": true,
    "checkFix": true,
    "proof": true,
    "allowNonArtworkFiles": false
  }
}
```

### Example with branding

```json
{
  "externalId": "TEST-ORDER-10001",
  "brand": {
    "color": "#1A73E8",
    "logo": "https://example.com/assets/logo.png"
  }
}
```

### Example with pre-supplied artwork

```json
{
  "externalId": "TEST-ORDER-10001",
  "artwork": {
    "url": "https://example.com/files/artwork.pdf"
  }
}
```

When an artwork URL is provided, the artwork is automatically processed without waiting for the end user to upload a file.

### Response

A successful response returns a Submit job object.

Important response fields include:

| Field          | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| `id`           | The Atomyx Submit API ID for the job                                                |
| `status`       | Current job status                                                                  |
| `externalId`   | The external ID supplied when creating the job                                      |
| `uploadURL`    | The URL where the end user can upload artwork                                       |
| `returnURL`    | The URL the user is redirected to after approving or rejecting artwork, if supplied |
| `metadata`     | Metadata displayed to the end user                                                  |
| `capabilities` | Enabled Submit capabilities                                                         |
| `brand`        | Branding applied to the Submit UI                                                   |
| `artwork`      | Artwork information, when artwork was supplied                                      |

### Status callbacks

If a `callbackURL` is supplied, Atomyx Submit sends status updates to that URL as the submission progresses.

Callbacks are sent as HTTP `POST` requests with JSON payloads.

See **Callbacks and Status Updates** for more detail.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.atomyx.io/atomyx-submit/implementation/api-integration/creating-jobs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.