Attachments


Overview

URL https://api.xero.com/api.xro/2.0/{Endpoint}/{Guid}/Attachments
Methods Supported GET, PUT, POST
Description Allows you to upload an attachment against an existing document (receipt or invoice)
Allows you to retrieve a list of attachments against a single existing document
Allows you to download the content of a specific attachments.

GET Attachments

The GET method supports retrieving a list of attachments or receiving the content of a single attachments.

To retrieve a list of attachments that have been uploaded against a document, you will need to construct a url that contains the Guid of the document. This url is in the format:

https://api.xero.com/api.xro/2.0/{Endpoint}/{Guid}/Attachments/

e.g.

GET /api.xro/2.0/Receipts/e59a2c7f-4078-a0f3-73537afcbba9/Attachments/
Authorization: OAuth...
Accept: text/xml

The response message will contain an xml or json summary of the attachments against the specified document:

<Response>
  <Attachments>
    <Attachment>
      <AttachmentID>e59a2c7f-1306-4078-a0f3-73537afcbba9</AttachmentID>
      <FileName>Image00394.png</FileName>
      <Url>https://api.xero.com/api.xro/2.0/Receipts/e59a2c7f-4078-a0f3-73537afcbba9/Attachments/Image00394.png</Url>
      <MimeType>image/png</MimeType>
      <ContentLength>10294</ContentLength>
    </Attachment>
  </Attachments>
</Response>

GET Attachment Content

To retrieve the content of an attachment, the Url element shown in the response of a ‘GET Attachments’ will retrieve the file.

The url will typically be in the following format:

https://api.xero.com/api.xro/2.0/{Endpoint}/{Guid}/Attachments/{Filename}

e.g.

GET /api.xro/2.0/Receipts/e59a2c7f-4078-a0f3-73537afcbba9/Attachments/Image00394.png
Authorization: OAuth...

The response message will contain the raw file content rather that was originally uploaded. The response won’t contain any xml or json encoded information:

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; Image00394.png

{RAW-IMAGE-CONTENT}

POST Attachments

Attachments can be uploaded to Xero using the PUT or POST method. To upload an attachment, a PUT or POST http request is made to a specific url created for the each attachment. The body of the http request contains the raw attachment content, not xml or json data that is normally used to upload data to Xero. Attachments can only be attached to documents that are of status DRAFT.

When uploading an attachment to Xero, the url that you’re posting to will typically be in the following format:

https://api.xero.com/api.xro/2.0/{Endpoint}/{Guid}/Attachments/{Filename}
{Endpoint} The name of the parent endpoint (e.g. Receipts, Invoices)
{Guid} The guid of the document that that attachment belongs to (e.g. ReceiptID or InvoiceID)
{Filename} The filename of the attachment that you are uploading

Note: 10 attachments can be uploaded per document. You can replace any attachment already uploaded by specifying the URL of the existing attachment e.g. https://api.xero.com/api.xro/2.0/{Endpoint}/{Guid}/Attachments/{Filename}

e.g.

POST /api.xro/2.0/Receipts/e59a2c7f-4078-a0f3-73537afcbba9/Attachments/Image00394.png
Authorization: OAuth...
Content Type: image/png
Content-Length: 10495
Accept: text/xml

{RAW-IMAGE-CONTENT}

The response message will contain a summary of the attachment that has been accepted into the API:

<Response>
  <Attachments>
    <Attachment>
      <AttachmentID>e59a2c7f-1306-4078-a0f3-73537afcbba9</AttachmentID>
      <FileName>Image00394.png</FileName>
      <Url>http://api.xero.com/api.xro/2.0/</Url>
      <MimeType>image/png</MimeType>
      <ContentLength>10294</ContentLength>
    </Attachment>
  </Attachments>
</Response>

PUT Attachments

The PUT method is identical to the POST method. If an attachment already exists on the specified document, then the attachment being uploaded will overwrite it.