Skip to content
 

Developer

See all pages
Try Xero Free

HTTP PUT and POST methods

The HTTP PUT and POST methods are used for sending information to the API. A PUT method will create new data in Xero, whereas a POST will either create new data or update existing data in Xero.

The XML must be sent in an html form parameter called “xml”.

To support extended character sets, the character encoding should be specified in the http header. Please ensure that the http header ‘Content-Type’ is specified correctly, and that the request body has actually been encoded using the encoding. The Xero API servers will use this information to correctly decode the data stream. We would recommend using UTF-8 encoding, as this is widely used by many application platforms.

The following example shows a simple PUT method, specifying the Content-Type as application/x-www-form-urlencoded and encoding type as UTF-8.

PUT /api.xro/2.0/Contacts HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: OAuth...
xml=%3CContacts%3E%3C%2FContacts%3E

The following example shows a simple POST method

POST /api.xro/2.0/Contacts HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: OAuth...
xml=%3CContacts%3E%3C%2FContacts%3E

When using POST to update an invoice or contact, you can specify the id of the object being updated in the url:

POST /api.xro/2.0/Invoices/INV-000394 HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: OAuth...
xml=%3CInvoices%3E%3C%2FInvoices%3E

Bulk Upload

It is possible to submit more than one invoice, credit note, contact, item or other entities of the same type in a single POST or PUT call.

If you plan to submit more than one entity per API call, we would recommend that you use append the summarizeErrors=false querystring to your API call. This ensures that every entity is returned back to you, each having their own status attribute.

e.g. POST /api.xro/2.0/Invoices?summarizeErrors=false HTTP/1.1

The following xml is a sample response of a bulk upload to the Invoices endpoint. Note that the status attribute of each Invoice can be OK, WARN or ERROR. 

<Response>
  ...
  <Invoices>
    <Invoice status="OK">
      ...
    </Invoice>
    <Invoice status="OK">
      ...
    </Invoice>
    <Invoice status="WARN">
      ...
    </Invoice>
    <Invoice status="ERROR">
      ...
    </Invoice>
  </Invoices>
</Response>

A WARN status indicated that there entity was successfully processed, but there are additional warnings added to the response. A ERROR status indicates that the entity could not be saved to Xero due to a validation error.

Debugging PUT and POST methods

To check that you’re sending PUT and POST messages to the Xero API correctly, we recommend that you use an HTTP proxy to record the raw request and response messages being transmitted. This will help you spot any incorrect parameters or encoding problems.