The purpose of this website is to fully describe the API of Odyssee: how it works, what you can do with it, the restrictions and some example code.

Always use constant: https://developers.odysseemobile.com/api to reach the latest version.

This website is composed of 2 parts :

- Help Guide

All information required to understand how the API works, how to commmunicate with it and how integration can be done.

- Reference

Generated documentation about the entities (objects), their properties (fields names and types) and their methods.

Your first API Call

As a first quick exercise, let's build a request to the API together. Imagine you want to add a company to Odyssee each time a company is created in your ERP

A request to the API is always composed of 3 parts: 1) Request URL, 2) Header and 3) Body.

1) Request URL

To work on the companies use the following request Url :https://developers.odysseemobile.com/api/Company

As we are adding a created company, use the method POST

2) Header

You need authentication to communicate with the API. (Go to "Authentification" for more info)

For this example we will use the following credentials :

Domain=TESTAPI , Username=APIUSer, Password=123456

Using the following format:

username:password@domain

filled with the above mentioned credentials, we get:

APIUser:123456@TESTAPI

If we then encode it in Base 64, we get:

QVBJVXNlcjoxMjM0NTZAVEVTVEFQSQ==

Finally the line on the header for authentification will be :

Authorization: Basic QVBJVXNlcjoxMjM0NTZAVEVTVEFQSQ==

Accept / Content-type : XML or JSON
The API support the 2 formats. By default and if nothing is found on the HTTP REQUEST, API will uses JSON.
If you want to receive data in XML format, use the following on the header
Accept: application/xml
If you want to send data (POST/PUT) in XML format, use the following on the header
Content-Type: application/xml

XML format is more easy to read, and used on this tutorial, let's use it.

Request Header

Authorization: Basic QVBJVXNlcjoxMjM0NTZAVEVTVEFQSQ==
Accept: application/xml
Content-Type: application/xml

I don't supply a line prefer: return=minimal because i want to have the the full represention of the object when adding / updating and not just have the id. Returning only th id should always beeing used when entity is not needed, for optimalization.

3) Body

By browsing the Reference documentation of the API, you can determine the fields you need/want to use. For this exercise we will fill the following:

code, name,email,phone,vat_reg_code For testing purposes, I will not specify the mandatory fields : sales_territory_id and sales_organization_id)

The Reference of the API include a namespace on the XML, but this is not mandatory, so let's skip it

Request body

<company>
<code>123456</code>
<name>Odyssee Mobile</name>
<email>info@odysseemobile.com</email>
<phone>+32 2 513 48 19</phone>
<vat_reg_code>BE0459288169</vat_reg_code>
</company>

Let's test this URL, Header and Body and check the response message...

HTTP Error 422 sales_territory_id, sales_territory_code or sales_territory must be provided

As we can see, the API returns an error and a message (Go to "Handling error" for more info). We need to fill the mandatory field sales_territory_id.
Because I don't want to synchronize the object Territories or Organization, I will use the concept of embedded entities and just supply its code.
All new database have by default 1 organization with code=DEFAULT and 1 territory with code=DEFAULT

Request body

<company>
<code>123456</code>
<name>Odyssee Mobile</name>
<email>info@odysseemobile.com</email>
<phone>+32 2 513 48 19</phone>
<vat_reg_code>BE0459288169</vat_reg_code>
<sales_territory_code>DEFAULT</sales_territory_code>
<sales_organization_code>DEFAULT</sales_organization_code>
</company>

The response we get now is the following:

HTTP Response 201.(Entity Created) with the object
<company>
<archived>false</archived>
<id>12345678-1234-1234-1234-123456789012</id>
<code>123456</code>
<name>Odyssee Mobile</name>
    ...
<sales_territory_id>21374b4a-0c88-4df3-bb6b-134cb62d2c70</sales_territory_id>
<sales_organization_id>0ea11d61-4e52-4eee-a945-bd8c26b52b45</sales_organization_id>
</company>

As we can see, the id (PrimaryKey) has been filled and all properties are returned and sales_territory+sales_organization_id have been filled with their Guid Primary Key

Let's now verify the company has well been created.
For this we use the same Request URL but add the id of the company behind it, as follows:

Request Url :https://developers.odysseemobile.com/api/Company(12345678-1234-1234-1234-123456789012), As we are now reading the database, the method used is GET

The response we get now is the following:

<company>
<archived>false</archived>
<id>12345678-1234-1234-1234-123456789012</id>
<code>123456</code>
<name>Odyssee Mobile</name>
<modified_dateutc>2015-03-28T12:14:50.28Z</modified_dateutc>
    ...
</company>

That's all !
In this example we have created a company in the odyssee database using an API call and then verified it was well created by our first call.
Congratulations, you have now done your 2 first API calls!