XML API Call and Response

Client applications must make an HTTP call to send a XML API request that includes a series of commands to the XML API endpoint. The XML API processes the commands in the XML API request and sends a response back to the client application.

This topic describes the HTTP Call Syntax, XML API Request Syntax, XML Data Object Syntax and XML API Response. You can also walk through an example of XML API request and response – see XML API Request and Response Sample Codes.

Note:

This guide provides formatted XML syntax and code samples with line returns and indentation throughout. Client applications typically send and receive XML content in its raw form (minified).

HTTP Call Syntax

            PUT /api.pl HTTP 1.1
Host: company-id.app.openair.com
Content-Type: application/xml

<!-- XML API request -->

HTTP method – Use either PUT or POST. Many libraries support either or both of these methods. From the XML API point of view, the PUT and POST are almost identical.
XML API endpoint – https://<account-domain>/api.pl
HTTP call headers:
- Host – The account-specific domain name for your OpenAir account is typically sent in the Host header. For more information about your account-specific domain name, see Your Account URLs.
- Content-Type – The XML API request in the body of the call uses XML syntax (application/xml).
HTTP Call Body – The XML API request. See XML API Request Syntax.

XML API Request Syntax

All requests sent to the XML API endpoint must use the following syntax.

            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request API_version="1.0" client="example client" client_ver="1.1" namespace="example" key="Your_API_Key">
   <Auth>
      <Login>
         <access_token>OAuth2_access_token</access_token>
      </Login>
   </Auth>

   <!-- XML API commands -->

</request>

In the example, Your_API_Key is your API key and OAuth2_access_token is the OAuth 2.0 access token obtained for the client application connecting to OpenAir.

Each request includes a XML prolog followed by a request element that contains the XML API commands.

XML prolog – OpenAir uses UTF-8 encoding to store and display characters. Specify the encoding in the XML prolog to ensure that non-Latin characters are handled and stored correctly.
```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
```

Root element – The request element is the root element and the immediate parent to all command elements in the XML API request.

The request element has the following attributes:

Attribute	Description
`API_version`	The `API_version` attribute value is always `1.0`
`client`	The name of your client application
`client_ver`	The version number of your client application
`namespace`	The API namespace assigned to your OpenAir account. See Step 1: Enabling API Access.
`key`	The API key assigned to your OpenAir account. See Step 1: Enabling API Access.

Attribute

Description

API_version

The API_version attribute value is always 1.0

client

The name of your client application

client_ver

The version number of your client application

namespace

The API namespace assigned to your OpenAir account. See Step 1: Enabling API Access.

key

The API key assigned to your OpenAir account. See Step 1: Enabling API Access.

All command elements are siblings and direct descendants of the request element.
- The first command in the request must be the Auth command. Successful authentication is required for all other commands except Time. See also Authentication.
- Subsequent commands can be used to interact with your OpenAir data. Depending on the operation, each command element may have a child business data object element. See the following topics for information about the type of information you can perform, and for information about the syntax and usage of each command.

Important:

The XML syntax is case sensitive. Element tags for XML API commands and objects always start with an uppercase character. Element tags for object properties always start with a lowercase character.

XML Data Object Syntax

An object element is defined by an XML start and end tag pair specifying the object type, and all the children property elements within this tags.

Each property element is defined by an XML start and end tag pair specifying the property name, and the property value within this tags.

                  <ObjectType>
         <property_name_1>property_value_1</property_name_1>
         <property_name_2>property_value_2</property_name_2>
         <property_name_3>property_value_3</property_name_3>
         
         <!-- Additional property elements -->
      
      </ObjectType>

Elements for properties referencing related object(s) by internal ID may include the attribute external or name. You can use this to look up the internal ID of a related object using its external ID or name as foreign key. See Related Object Lookup Using the XML API.

Property elements with empty values can be represented using an XML start and end tag pair with no content (such as the property_name_1 element in the following example), or with a self-closing XML tag, if you want to set the property to an empty value (such as the property_name_2 element in the following example).

                     <property_name_1></property_name_1>
         <property_name_2/>

Property elements can be omitted if you do not want to set a value.

Property values can either be text or an XML substructure. Properties containing address information, date or time information, and account or user settings use have an XML substructure as property value. These XML substructures use the same syntax as for XML data objects. The following example shows the XML syntax for a property including address information:

                     <addr>
            <Address>
               <first>John</first>
               <last>Smith</last>
               <phone>123-345-6789</phone>
            </Address>
         </addr>

For more information about supported business object types and their properties, see XML and SOAP API Business Object Reference.

XML API Response

The XML API response uses a syntax similar to the request sent to the XML API endpoint.

            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
   <Auth status = "0"></Auth >

   <!-- XML API command responses -->

</response>

Each response includes a XML prolog followed by a response element that contains the responses to each XML API command sent in the request.

XML prolog – OpenAir uses UTF-8 encoding to store and display characters.
```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
```

Root element – The response element is the root element and the immediate parent to all command response elements in the XML API response.

The response element has no attributes unless the XML request is malformed, in which case it has a status attribute set to 1.

Attribute	Description
`status`	Only included and has the value `1` if the XML request is malformed. `<response status="1">unclosed token at line 1, column 322</response>`

Attribute

Description

status

Only included and has the value 1 if the XML request is malformed.

<response status="1">unclosed token at line 1, column 322</response>

All command response elements are siblings and direct descendants of the response element.
- Command response elements in the response follow the same sequence as the command elements in the request.
- The names of command response elements in the response are the same as the names of the corresponding command elements in the request.
  
  The first child element is an Auth element returned in response to the Auth command in the request.
  
  Subsequent elements show the outcome of each subsequent commands in the request. Depending on the operation, each of these element may have children business data object elements. For example, if the request included a Read command element and a CreateUser command element, the response includes a Read element and a CreateUser element in the same order. The Read element has up to 1,000 children (objects of the requested type), the CreateUser has one child (User object).
- Each command response element includes a status attribute which indicates the success or failure of the operation. For more information about the command response status, see Error Codes.

XML API Request and Response Sample Codes

The following XML API request sample code includes the following operations:

Auth element – Authentication using OAuth 2.0 access token.
Time element – Retrieves the time from the OpenAir API server.
Read element – Retrieves up to 100 invoices from OpenAir starting with index 0.
CreateUser element – Add the user John Smith to the account. In this example, the value specified for the Company ID includes a typographic error.

            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request API_ver="1.0" client="sample code" client_ver="1.1" namespace="example" key="Your_API_Key">
   <Auth>
      <Login>
         <access_token>OAuth2_access_token</access_token>
      </Login>
   </Auth>
   <Time/>
   <Read type="Invoice" limit="0,100" method="all"/>
   <CreateUser>
      <Company>
         <nickname>company_id_with_typo_error</nickname>
      </Company>
      <User>
         <name>jsmith</name>
         <password>new_user_password</password>
         <taapprover>16</taapprover>
         <teapprover>16</teapprover>
         <addr>
            <Address>
               <first>John</first>
               <last>Smith</last>
               <phone>123-345-6789</phone>
            </Address>
         </addr>
      </User>
   </CreateUser>
</request>

In the example, Your_API_Key is your API key and OAuth2_access_token is the OAuth 2.0 access token obtained for the client application connecting to OpenAir.

The XML API response returns:

Auth element – A successful authentication status.
Time element – The time on the OpenAir API server as a Date object.
Read element – Up to 100 Invoice objects. There are only 2 invoice records in the example OpenAir account.
CreateUser element – An error status with error code 201. A subsequent request can be sent to retrieve the error description corresponding to error code 201, if required. See Error Codes.

            <response>
   <Auth status="0"></Auth>
   <Time status="0">
      <Date>
         <day>13</day>
         <month>02</month>
         <year>2024</year>
         <hour>23</hour>
         <minute>59</minute>
         <second>01</second>
      </Date>
   </Time>
   <Read status="0">
      <Invoice>
         <id>1</id>
         <number>234</number>
         <customerid>204</customerid>
         <total>99.00</total>
         <tax>0.00</tax>
         <balance>80.00<balance>
         <draw>1</draw>
         <credit/>
         <credit_reason/>
         <terms/>
         <emailed>
            <Date>
               <day>13</day>
               <month>2</month>
               <year>2024</year>
               <hour>0</hour>
               <minute>0</minute>
               <second>0</second>
            </Date>
         </emailed>
      </Invoice>
      <Invoice>
         <id>4</id>
         <number>983</number>
         <customerid>204</customerid>
         <total>12.00</total>
         <tax>0.00</tax>
         <balance>50.00<balance>
         <draw>1</draw>
         <credit/>
         <credit_reason/>
         <terms/>
         <emailed/>
      </Invoice>
   </Read>
   <CreateUser status="201"></CreateUser>
</response>