# Files and Attachments

## HTTPS Multipart Upload

Files can be transferred via HTTPS multipart upload, which allows large files to be sent via API.

### Upload a File with Data

Details of how the `upload` endpoint can be used to upload files that contain orders or trackings in the parcelLab system are described below.

{% hint style="info" %}
The file types allowed are CSV, XML, fixed file, and EDI.
{% endhint %}

<details>

<summary><mark style="color:green;">POST</mark> Upload a File with Data</summary>

You can send a data file containing orders or trackings to be processed in the parcelLab system using the `upload` endpoint.

The following request limits are applicable for this endpoint:

* The maximum file size for uploads is 500MB.

**Note:** Split larger files into multiple files before uploading.

* The connection time limit is 300 seconds.

**Note:** If your upload speeds are slow and your upload takes over five minutes, the upload will be aborted.

* Each unique file name can be transferred once per millisecond only.

**Note:** If the same file is uploaded twice within the same millisecond, only the later file will be received and processed.

To use this API, you need your parcelLab `user_id` and `API token` for authentication.

The details of the Upload a File with Data API are described in the following section.

**API Details**

<mark style="color:green;">`POST`</mark> `https://api.parcellab.com/upload/data/:type`

**Path Parameters**

| Name | Type   | Description                                                                                                                                                 |
| ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | Any free text string `[a-zA-Z0-9]` describing the file type, could be the origin system name. Each different data file format needs to have their own type. |

**Header**

| Name  | Type   | Description         |
| ----- | ------ | ------------------- |
| user  | string | parcelLab user ID   |
| token | string | parcelLab API token |

**Request Body**

| Name | Type   | Description           |
| ---- | ------ | --------------------- |
| data | object | Multipart upload file |

**Responses**

* 200 - accepted
* 403 - invalid credentials or no write scope of token
* 413 - server rejects upload because file is too large
* 500 - server failed when processing upload, please retry

An example request is displayed below to show the format for uploading a file (for example: where `<type>` might be `ups`).

```bash
curl --request POST 'https://api.parcellab.com/upload/data/<type>' \
--header 'user: <parcelLab-user-id>' \
--header 'token: <parcelLab-token-with-write-scope>' \
--form 'data=@"path/to/your/file.txt"'
```

</details>

### Upload an Attachment File

Details of how the `upload` endpoint can be used to upload attachment files for communications in the parcelLab system are described below.

{% hint style="info" %}
The maximum file size allowed is 1MB.
{% endhint %}

<details>

<summary><mark style="color:green;">POST</mark> Upload an Attachment File</summary>

You can upload an attachment file to be used in communications using the `upload` endpoint.

To use this API, you need your parcelLab `user_id` and `API token` for authentication.

The details of the Upload an Attachment File API are described in the following section.

**API Details**

<mark style="color:green;">`POST`</mark> `https://api.parcellab.com/upload`

**Header**

| Name  | Type   | Description         |
| ----- | ------ | ------------------- |
| user  | number | parcelLab user ID   |
| token | string | parcelLab API token |

**Request Body**

| Name        | Type   | Description                                                                        |
| ----------- | ------ | ---------------------------------------------------------------------------------- |
| filename    | string | Name of the file.                                                                  |
| file        | string | File to be uploaded as Base64 encoded string.                                      |
| encoding    | string | Base64                                                                             |
| contenttype | string | Any string that specifies the content-type of data sent (for example: image/jpeg). |

**Responses**

* 200 - accepted

An example request is displayed below to show the format for uploading an attachment.

```bash
curl --location 'https://api.parcellab.com/upload' \
--header 'user: 100' \
--header 'token: parcelLabAPItoken-30characters' \
--data '{
    "filename": "name of the file",
    "file": "file to be uploaded as Base64 encoded string",
    "encoding": "base64",
    "contenttype": "Content-Type of transmitted data, e.g. image/jpeg"
}'
```

</details>


---

# Agent Instructions: 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.parcellab.com/docs/developers/v2/orders/files-and-attachments.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.