Attachments

Explore Invoice attachments and Bill attachments endpoints in Swagger.

Overview

The Codat API supports pulling and pushing of file attachments, specifically for invoices and bills.

👍

Retrieving attachments

If a company is authorised, then you can query the Codat API to read, download and upload attachments, without requiring a fresh sync of data.

Unlike other data types, Codat doesn't support sync settings for attachments.

Xero and QuickBooks Online are the currently supported platforms for pushing attachments.

❗️

Pushing attachments

Codat currently supports the pushing of single invoice and bill attachments for Xero and QuickBooks online.

Codat's API doesn't allow the upload of multiple attachments in a single API call.

Data model

Field

Type

Description

id

string

Identifier for the attachment, unique for the company in the accounting platform.

name

string

Name of the attachment file.

contentType

string

File type of the attachment.

This is represented by appending the file type to the IETF standard file naming requirements.

For example, for a jpeg file the output is image/jpeg.

Supported file types vary per platform. See section below on the available options for pushing attachments to an accounting platform.

dateCreated

string
See date

Date the attachment was uploaded and attached in the accounting platform.

filesize

integer

File size in bytes. For example, if this reads 46153, then the file size is 46kb.

includeWhenSent

boolean

If true then the attachment is included with the associated bill or invoice when it is printed, emailed, or sent to a customer, if the underlying accounting platform allows this.

Pushing attachments

Using Postman to attach a file to an invoice

If you use Postman, there are some extra steps you need to follow to attach a file to an invoice.

  1. Set up a POST request, in a similar way to the example, to the following endpoint: POST /companies/{companyId}/connections/{dataConnectionId}/push
    /invoices/{invoiceId}/attachment
    .
  2. In the request setup, select Body.
  3. From the Body menu, select form-data.
  4. Click in the first KEY row, and then from the File list, select File.
  1. In the corresponding VALUE field, select Select Files and browse to the file you wish to attach.
  1. Now you are ready to make the request.

HTTP example for attaching a file

POST /companies/{companyId}/connections/{dataConnectionId}/push/invoices/{invoiceId}/attachment

Content-Type: multipart/form-data; boundary=yourBoundaryString

--yourBoundaryString
Content-Type: application/json
Content-Disposition: form-data; name="yourFileMetaData"

{ "incldeWhenSent": false }
--yourBoundaryString
Content-Type: application/octet-stream
Content-Disposition: form-data; name="yourFileData"; filename="TEST_SEND_FILE.txt"

HELLO WORLD!
--yourBoundaryString--

Options for pushing attachments to the accounting platform

Xero

{
    "type": "File",
    "displayName": "File Attachment",
    "description": "Attach a file to an Xero entity.",
    "properties": {
        "file": {
            "type": "Number",
            "displayName": "File Size",
            "description": "Size of the file.",
            "required": false,
            "validation": {
                "warnings": [
                    {
                        "field": "fileSize",
                        "details": "File size may not exceed 4 MB."
                    }
                ]
            }
        },
        "fileExtension": {
            "type": "String",
            "displayName": "File extension",
            "description": "Must be an accepted Mime Type as derived from the file extension.",
            "options": [
                {
                    "value": ".7z",
                    "type": "String",
                    "displayName": "7Z",
                    "required": false
                },
                {
                    "value": ".bmp",
                    "type": "String",
                    "displayName": "BMP",
                    "required": false
                },
                {
                    "value": ".csv",
                    "type": "String",
                    "displayName": "CSV",
                    "required": false
                },
                {
                    "value": ".doc",
                    "type": "String",
                    "displayName": "DOC",
                    "required": false
                },
                {
                    "value": ".docx",
                    "type": "String",
                    "displayName": "DOCX",
                    "required": false
                },
                {
                    "value": ".eml",
                    "type": "String",
                    "displayName": "EML",
                    "required": false
                },
                {
                    "value": ".gif",
                    "type": "String",
                    "displayName": "GIF",
                    "required": false
                },
                {
                    "value": ".jpeg",
                    "type": "String",
                    "displayName": "JPEG",
                    "required": false
                },
                {
                    "value": ".jpg",
                    "type": "String",
                    "displayName": "JPG",
                    "required": false
                },
                {
                    "value": ".keynote",
                    "type": "String",
                    "displayName": "KEYNOTE",
                    "required": false
                },
                {
                    "value": ".msg",
                    "type": "String",
                    "displayName": "MSG",
                    "required": false
                },
                {
                    "value": ".numbers",
                    "type": "String",
                    "displayName": "NUMBERS",
                    "required": false
                },
                {
                    "value": ".odf",
                    "type": "String",
                    "displayName": "ODF",
                    "required": false
                },
                {
                    "value": ".ods",
                    "type": "String",
                    "displayName": "ODS",
                    "required": false
                },
                {
                    "value": ".odt",
                    "type": "String",
                    "displayName": "ODT",
                    "required": false
                },
                {
                    "value": ".pages",
                    "type": "String",
                    "displayName": "PAGES",
                    "required": false
                },
                {
                    "value": ".pdf",
                    "type": "String",
                    "displayName": "PDF",
                    "required": false
                },
                {
                    "value": ".png",
                    "type": "String",
                    "displayName": "PNG",
                    "required": false
                },
                {
                    "value": ".ppt",
                    "type": "String",
                    "displayName": "PPT",
                    "required": false
                },
                {
                    "value": ".pptx",
                    "type": "String",
                    "displayName": "PPTX",
                    "required": false
                },  
                {
                    "value": ".rar",
                    "type": "String",
                    "displayName": "RAR",
                    "required": false
                },              
                {
                    "value": ".rtf",
                    "type": "String",
                    "displayName": "RTF",
                    "required": false
                },
                {
                    "value": ".rtf",
                    "type": "String",
                    "displayName": "RTF",
                    "required": false
                },
                {
                    "value": ".tif",
                    "type": "String",
                    "displayName": "TIF",
                    "required": false
                },
                {
                    "value": ".tiff",
                    "type": "String",
                    "displayName": "TIFF",
                    "required": false
                },
                {
                    "value": ".txt",
                    "type": "String",
                    "displayName": "TXT",
                    "required": false
                },
                {
                    "value": ".xls",
                    "type": "String",
                    "displayName": "XLS",
                    "required": false
                },
                {
                    "value": ".xlsx",
                    "type": "String",
                    "displayName": "XLSX",
                    "required": false
                },
                {
                    "value": ".zip",
                    "type": "String",
                    "displayName": "ZIP",
                    "required": false
                }
            ],
            "required": false
        }
    },
    "required": true
}

QuickBooks Online

{
  "type": "MultiPart",
  "displayName": "File",
  "description": "Attach a file to a Quickbooks Online entity.",
  "properties": {
    "file": {
      "type": "File",
      "displayName": "File",
      "description": "File attachment.",
      "properties": {
        "fileSize": {
          "type": "Number",
          "displayName": "File Size",
          "description": "Size of the file.",
          "required": false,
          "validation": {
            "warnings": [
              {
                "field": "file.fileSize",
                "details": "The file size must not exceed 100 MB."
              }
            ]
          }
        },
        "fileExtension": {
          "type": "String",
          "displayName": "File extension",
          "description": "Must be an accepted Mime Type as derived from the file extension.",
          "options": [
            {
              "value": ".ai",
              "type": "String",
              "displayName": "AI",
              "required": false
            },
            {
              "value": ".csv",
              "type": "String",
              "displayName": "CSV",
              "required": false
            },
            {
              "value": ".doc",
              "type": "String",
              "displayName": "DOC",
              "required": false
            },
            {
              "value": ".docx",
              "type": "String",
              "displayName": "DOCX",
              "required": false
            },
            {
              "value": ".eps",
              "type": "String",
              "displayName": "EPS",
              "required": false
            },
            {
              "value": ".gif",
              "type": "String",
              "displayName": "GIF",
              "required": false
            },
            {
              "value": ".jpeg",
              "type": "String",
              "displayName": "JPEG",
              "required": false
            },
            {
              "value": ".jpg",
              "type": "String",
              "displayName": "JPG",
              "required": false
            },
            {
              "value": ".ods",
              "type": "String",
              "displayName": "ODS",
              "required": false
            },
            {
              "value": ".pages",
              "type": "String",
              "displayName": "PAGES",
              "required": false
            },
            {
              "value": ".pdf",
              "type": "String",
              "displayName": "PDF",
              "required": false
            },
            {
              "value": ".png",
              "type": "String",
              "displayName": "PNG",
              "required": false
            },
            {
              "value": ".rtf",
              "type": "String",
              "displayName": "RTF",
              "required": false
            },
            {
              "value": ".tif",
              "type": "String",
              "displayName": "TIF",
              "required": false
            },
            {
              "value": ".txt",
              "type": "String",
              "displayName": "TXT",
              "required": false
            },
            {
              "value": ".xls",
              "type": "String",
              "displayName": "XLS",
              "required": false
            },
            {
              "value": ".xlsx",
              "type": "String",
              "displayName": "XLSX",
              "required": false
            },
            {
              "value": ".xml",
              "type": "String",
              "displayName": "XML",
              "required": false
            }
          ],
          "required": false
        }
      },
      "required": true
    },
    "metadata": {
      "type": "Object",
      "displayName": "Metadata",
      "description": "File metadata.",
      "properties": {
        "includeWhenSent": {
          "type": "Boolean",
          "displayName": "Include When Sent",
          "description": "This field indicates whether or not the attachment is sent with the transaction to the customer (this can also be achieved by invoking the Send email endpoint for the object).",
          "required": false
        },
        "contentType": {
          "type": "String",
          "displayName": "File Content Type",
          "description": "This field indicates the file content type.",
          "required": true,
          "validation": {
            "information": [
              {
                "field": "metadata.contentType",
                "details": "If not specified, content type of file part of parent multipart is used."
              }
            ]
          }
        }
      },
      "required": true
    }
  },
  "required": true,
  "validation": {
    "warnings": [
      {
        "field": "metadata",
        "details": "content type must be application/json"
      }
    ],
    "information": [
      {
        "field": "file",
        "details": "One file per request."
      }
    ]
  }
}

Did this page help you?