---
title: File Attachments
slug: dev/file-attachments
docTags: 
createdAt: 2021-10-02T14:00:23.000Z
---

Invoiced supports attaching files to invoices to give customers more context about a bill.

## Usage

Files can be attached to invoices through the dashboard or programmatically through the API. In this guide, we will walk you through the complete steps to attach a file to an invoice through the API.

### 1. Create a file

You can upload a file using our API or host your file somewhere publicly accessible. 

To upload a local file, make the following request.

```curl
curl https://api.invoiced.com/files \
-u {API_KEY}: \
-H "Content-Type:multipart/form-data" \
-F "file=@/path/to/your/file/yourfilename.pdf" \
-F "name=file"
```

If your file is publicly hosted, make this request instead.

:::CodeblockTabs
```curl
curl "https://api.invoiced.com/files" \
  -u {API_KEY}: \
  -d url="https://www.invoiced.com/img/logo-invoice.png" \
  -d name="logo-invoice.png" \  # filename
  -d size=6936 \                # size in bytes
  -d type="image/png"           # MIME type
```

```java
import com.invoiced.entity.Connection;
import com.invoiced.entity.File;

Connection invoiced = new Connection("{YOUR_API_KEY}", false);

File file = invoiced.newFile();
file.url = "https://www.invoiced.com/img/logo-invoice.png";
file.size = 6936;
file.name = "logo-invoice.png";
file.type = "image/png";
file.create();
```

```php
<?php
$invoiced = new Invoiced\Client("{YOUR_API_KEY}");

$file = $invoiced->File->create([
  'url' => "https://www.invoiced.com/img/logo-invoice.png",
  'name' => "logo-invoice.png", // filename
  'size' => 6936,               // size in bytes
  'type' => "image/png"         // MIME type
]);
```

```python
import invoiced
client = invoiced.Client("{YOUR_API_KEY}")

file = client.File.create(
  url="https://www.invoiced.com/img/logo-invoice.png",
  name="logo-invoice.png",  # filename
  size=6936,                # size in bytes
  type="image/png"          # MIME type
)
```

```ruby
require "invoiced"
invoiced = Invoiced::Client.new("{YOUR_API_KEY}")

file = invoiced.File.create(
  :url => "https://www.invoiced.com/img/logo-invoice.png",
  :name => "logo-invoice.png",  # filename
  :size => 6936,                # size in bytes
  :type => "image/png"          # MIME type
)
```
:::

### 2. Attach to an invoice

Once you have created your file, you can attach it to an invoice. This is done by passing in an array of file IDs through the `attachments` parameter when creating or editing an invoice.

In this example, we are going to show how to attach a single file when creating a new invoice:

:::CodeblockTabs
```curl
curl "https://api.invoiced.com/invoices" \
  -u {API_KEY}: \
  # invoice parameters...
  -d attachments[]={FILE_ID}
```

```java
import com.invoiced.entity.Attachment;
import com.invoiced.entity.Invoice;

Invoice invoice = invoiced.newInvoice();
// invoice parameters...
Attachment[] attachments = new Attachment[1];
attachments[0] = new Attachment();
attachments[0].file = file.id;
invoice.attachments = attachments;
invoice.create();
```

```php
<?php
$invoiced->Invoice->create([
  // invoice parameters...
  'attachments' => [$file->id]
]);
```

```python
invoice = client.Invoice.create(
  # invoice parameters...
  attachments=[file.id]
)
```

```ruby
invoice = invoiced.Invoice.create(
  # invoice parameters...
  :attachments => [file.id]
)
```
:::

And the file is now attached! It will be available in the client view and dashboard as a downloadable attachment.

### Retrieving attachments for an invoice

You can also retrieve the existing file attachments for an invoice with a simple API query. This might be useful to synchronize the attachments for an invoice with your internal systems.

:::ApiMethodV2
```json
{
  "tab": "examples",
  "url": "https://api.invoiced.com/invoices/{id}/attachments",
  "name": "List Invoice Attachments",
  "method": "GET",
  "request": {
    "pathParameters": [
      {
        "kind": "required",
        "name": "id",
        "type": "Integer",
        "description": "Invoice Id"
      }
    ],
    "queryParameters": [],
    "headerParameters": [],
    "bodyDataParameters": [],
    "formDataParameters": []
  },
  "results": {
    "languages": [
      {
        "id": "dSyiav7J7Wy9NHE6my078",
        "code": "[\n  {\n    \"id\": 13,\n    \"file\": {\n      \"id\": 13,\n      \"object\": \"file\",\n      \"name\": \"logo-invoice.png\",\n      \"size\": 6936,\n      \"type\": \"image/png\",\n      \"url\": \"https://www.invoiced.com/img/logo-invoice.png\",\n      \"created_at\": 1464625855\n    },\n    \"created_at\": 1464625855\n  }\n]",
        "language": "200"
      }
    ],
    "selectedLanguageId": "dSyiav7J7Wy9NHE6my078"
  },
  "examples": {
    "languages": [
      {
        "id": "H4bek1JgxcY_h_wlsadDu",
        "code": "curl \"https://api.invoiced.com/invoices/{INVOICE_ID}/attachments\" \\\n  -u {API_KEY}:",
        "language": "curl"
      },
      {
        "id": "s19uJTxg2d5LHQO7CAuSe",
        "code": "import com.invoiced.entity.Attachment;\n\nAttachment[] attachments = invoice.listAttachments();",
        "language": "java"
      },
      {
        "id": "V-Y9amMP5dwoemYu2lgeu",
        "code": "<?php\nlist($attachments, $metadata) = $invoice->attachments();",
        "language": "php"
      },
      {
        "id": "xSTg8MVobsn4kBwCj0CPY",
        "code": "attachments, metadata = invoice.attachments()",
        "language": "python"
      },
      {
        "id": "L2kW4IiA0aCQcdsV0jj_0",
        "code": "attachments, metadata = invoice.attachments",
        "language": "ruby"
      }
    ],
    "selectedLanguageId": "H4bek1JgxcY_h_wlsadDu"
  },
  "description": "Get a list of attachments for an invoice",
  "currentNewParameter": {
    "label": "Path Parameter",
    "value": "pathParameters"
  },
  "autoGeneratedAnchorSlug": "list-invoice-attachments",
  "legacyHash": "5nSSvu7I2JA04-HGjf0kL"
}
```
:::