API

Application Programming Interface

InvoiceXpress Documentation



Create


clients.create

Creates a new client.

You call this method by submitting an HTTP POST request to the following URL with the xml data of the new client information on the request body:

https://{account-name}.app.invoicexpress.com/clients.xml
Header

Content-Type: application/xml; charset=utf-8

Body
<client>
  <name>Ricardo Pereira</name>
  <language>pt</language>
  <code>123</code>
  <email>someone@example.com</email>
  <address>Saldanha</address>
  <city>Lisbon</city>
  <postal_code>1750-455</postal_code>
  <fiscal_id>508025338</fiscal_id>
  <website>www.invoicexpress.com</website>
  <phone>2313423424</phone>
  <fax>2313423425</fax>
  <preferred_contact>
    <name>Ricardo Pereira</name>
    <email>someone@example.com</email>
    <phone>2233442233</phone>
  </preferred_contact>
  <observations>Computer Processed</observations>
  <send_options>1</send_options>
</client>

Parameters

Parameters are the data you will pass with the call.

Parameter Required Description
api_key Yes Your secret identifier. You can find your API Key under Account >> API in the Account section.
client / name Yes Client name, normally used for a company name.
client / code Yes Client code, your specific code for the client.
client / email No Client email address. Must be a valid email address ex: foo@bar.com
client / language No Client language. May be en, pt or es; defaults to the account language.
client / address No Client company address.
client / city No Client’s city.
client / postal_code No Client’s postal code for it’s company address.
client / country No Country, normally used for a company country. Although country is optional, when supplied, it should match one of the country list on the Appendix of this Documentation
client / fiscal_id No The client fiscal ID (Número de Contribuinte)
client / website No The client web address
client / phone No The client phone number
client / fax No The client fax number
fiscal_id No Client fiscal id
preferred contact / name No Name of the preferred contact on your new client
preferred contact / email No Email of the preferred contact on your new client.
preferred contact / phone No Phone number of the preferred contact on your new client.
observations No Default observations for the client, the text in here will be added to the observations field of all the invoices sent to this client.
send_options No Send options for the client. Available options are: 1 - send only the original document / 2 – the original and duplicate / 3 – the original, duplicate and triplicate. These affect the generated pdf.

Return Values

These are the results that will be returned on success and error.

Success
HTTP : 201 CREATED
<client>
  <id>1</id>
  <name>Ricardo Pereira</name>
  <email>someone@example.com</email>
  <address>Saldanha</address>
  <city>Lisbon</city>
  <postal_code>1750-455</postal_code>
  <fiscal_id>508025338</fiscal_id>
  <website>www.invoicexpress.com</website>
  <phone>2313423424</phone>
  <fax>2313423425</fax>
  <preferred_contact>
    <name>Ricardo Pereira</name>
    <email>someone@example.com</email>
    <phone>2233442233</phone>
  </preferred_contact>
  <observations>Computer Processed</observations>
  <send_options>1</send_options>
</client>
Error
Code Description
HTTP: 401 Access denied The API Key parameter is missing or is incorrectly entered.
HTTP: 422 Unprocessable Entity Some parameters were incorrect.

Possible errors for HTTP: 422

<errors>
  <error>Name has already been taken</error>
  <error>Client contact is invalid</error>
  <error>Send options is not a number</error>
  <error>Send options must be within 1 and 3</error>
  <error>Preferred contact: email must be an email</error>
</errors>