Attachments
| 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 AP 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, Currently only one attachment can be uploaded per document. The default behaviour for both PUT and POST methods is to replace any existing attachment with the one being uploaded.
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.