> 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.md).

# API Integration

Atomyx Submit can be integrated with external systems through the Submit API.

This allows artwork submission to operate as part of the wider order lifecycle rather than as an isolated portal.

Use the API when an external platform needs to create Submit jobs programmatically, pass artwork or job metadata into Submit, or connect Submit to an e-commerce, MIS, workflow, or upload portal.

This section explains how to authenticate, which environments to use, how to create jobs, and how to test API calls using the interactive API reference.

### In this section

* Submit API Overview
* Authentication
* Getting an API Key
* Environments
* Creating Jobs
* API Reference
* Testing API Calls
* Callbacks and Status Updates

### Typical integration flow

A common integration flow looks like this:

1. the ERP or ordering system creates an order
2. it calls the Atomyx Submit API to create a submission session
3. product-specific parameters are passed into the session
4. the customer completes the submission flow in Atomyx Submit
5. the portal calls back to the ERP with status, file references, and proof data
6. the ERP updates the order status and continues the workflow

### Common parameters passed into a submission session

Typical parameters include:

* product width
* product height
* product shape
* bleed
* safety zone
* finishing options
* language
* callback URL
* order reference

These values allow the portal and processing profiles to behave correctly for the selected product.

### Callbacks

Atomyx Submit can notify the ERP through callback URLs associated with the submission session.

Typical callback content includes:

* current submission status
* processed file URLs
* proof page URL
* preflight report URL
* structured error details where relevant

Common statuses may include:

* uploaded
* preflighting
* preflight passed
* preflight failed
* proof generated
* approved
* rejected

### Security considerations

When integrating Submit:

* keep API keys on the backend, never in public client-side code
* validate callback requests server-side
* use HTTPS for callback endpoints
* verify HMAC signatures where used
* treat the ERP as the trusted receiver of results, not the direct upload handler

### Practical advice

Design the integration so that:

* the ERP remains the system of record
* the portal handles file submission and review
* callbacks update order state clearly
* status transitions are explicit and traceable

### Important note

The public Submit API currently uses the production environment.

Production API requests create real Submit jobs. When testing, use clearly identifiable test external IDs, avoid real customer data unless required, and only use artwork files that are safe for testing.

### Next steps

* Go to **Preflight Configuration**
* Go to **Manage Plug-in Configuration**
* Go to **Submit Troubleshooting** if callbacks, authentication, or payloads are failing


---

# 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.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.