Businesses running on Odoo often reach a point where they need it to talk to something else. A mobile app. A customer portal. A third-party logistics platform. That conversation happens through an API, and when it comes to modern software integrations, REST is the language most developers prefer.

If you have been wondering how the Odoo REST API works and how to structure your requests correctly, this guide is your starting point.

Understanding the Odoo REST API Format

Before writing a single line of integration code, you need to understand how Odoo REST API format is structured and what makes it work differently from standard REST implementations.

What Makes Odoo REST API Different?

Odoo does not expose a traditional REST API out of the box the way some platforms do. Its native communication layer relies on RPC-based protocols. REST in Odoo is built on top of its HTTP controller system, where developers define custom routes and expose data through JSON endpoints. This gives you a lot of flexibility but also means you need to understand the structure before you start.

How Odoo Structures Its Endpoints?

Each endpoint in Odoo follows a URL pattern tied to your instance:


https://your-instance.odoo.com/api/resource-name

The route is defined in Python using Odoo’s controller system, and you control what data goes in and what comes back out.

Key Components of Every Request

Four things make up any Odoo REST API call:

URL points to the specific resource or action you are targeting on your Odoo server.

Headers carry metadata about the request. At minimum, you need:

 
Content-Type: application/json
Authorization: Bearer your-api-key

Body is the JSON payload sent with POST and PUT requests. It carries the data you want to create or modify.

Response is the JSON object Odoo returns. A clean response structure looks like this:

 {

  "status": "success",

  "data": {

    "id": 7,

    "name": "Demo Customer"

  } }

Odoo API Types: Which One Should You Use?

Odoo supports three communication protocols, and knowing when to use each one saves a lot of debugging time.

ProtocolFormatBest Use Case
XML-RPCXMLOlder integrations, legacy systems
JSON-RPCJSONInternal Odoo-to-Odoo calls
RESTJSONMobile apps, web apps, third-party tools

REST wins for external integrations because it is lightweight, stateless, and supported by virtually every modern development framework. If you are building anything user-facing or connecting to a non-Odoo system, REST is the right choice.

Setting Up Authentication for Odoo REST API

Generating Your API Key

Before you send a single request, you need an Odoo API key tied to a user account. We have a dedicated step-by-step guide on how to generate your Odoo API key in 4 simple steps. Follow that first, then come back here.

Adding Your Key to Request Headers

Once you have your key, every request must include it in the Authorization header:

Authorization: Bearer YOUR_ODOO_API_KEY Content-Type: application/json

Common Authentication Errors

401 Unauthorized shows up when the key is missing, expired, or formatted incorrectly. Re-check your header and confirm the key is active in your Odoo user settings.

403 Forbidden means the key is valid but the user behind it lacks permission for the action you are attempting. Go into Odoo access rights and adjust the user role accordingly.

Common HTTP Methods in Odoo REST API

GET: Reading Data

GET requests pull data without changing anything. Use it to fetch a customer record:

GET /api/customers/5

POST: Creating New Records

POST sends data to create something new. Example for adding a contact:

Authorization: Bearer YOUR_ODOO_API_KEY
Content-Type: application/json

PUT: Updating Existing Records

PUT modifies a record that already exists. Pass the record ID in the URL:

PUT /api/customers/5
Body: { "phone": "033xxxxxxxx" }

DELETE: Removing Records

DELETE permanently removes a record from Odoo:

DELETE /api/customers/5

Building a Real Use Case: Mobile App Fetching Customer Data

A sales team uses a mobile app in the field. They need to pull customer details from Odoo in real time without logging into the backend.

Step-by-Step Code Walkthrough

Step 1: Create the controller in Odoo

from odoo import http
from odoo.http import request

class MobileAPI(http.Controller):

    @http.route('/api/mobile/customer/<int:customer_id>',
                type='http', auth='user', methods=['GET'], csrf=False)
    def get_customer(self, customer_id, **kwargs):
        partner = request.env['res.partner'].sudo().browse(customer_id)

        if not partner.exists():
            return request.make_response(
                '{"status": "error", "message": "Customer not found"}',
                headers=[('Content-Type', 'application/json')]
            )

        data = {
            "status": "success",
            "data": {
                "id": partner.id,
                "name": partner.name,
                "email": partner.email,
                "phone": partner.phone
            }
        }

        import json
        return request.make_response(
            json.dumps(data),
            headers=[('Content-Type', 'application/json')]
        )

Step 2: Call it from your mobile app

Send a GET request to:

GET https://your-instance.odoo.com/api/mobile/customer/5
Authorization: Bearer YOUR_API_KEY

Step 3: Handle the response

Parse the JSON, check the status field, and display the customer name, email, and phone in your app UI.

Error Handling in Odoo REST API

Always build error handling into your integration from day one, not as an afterthought.

Code Meaning What To Do
400 Bad Request Validate your JSON body before sending
401 Unauthorized Check your API key and header format
403 Forbidden Review user permissions in Odoo
404 Not Found Confirm the endpoint URL is correct
500 Server Error Check your controller logic for exceptions

Wrap your controller code in try-except blocks so your API always returns a clean JSON error instead of a raw Python traceback:key

 try:
    partner = request.env['res.partner'].sudo().browse(customer_id)
    # your logic here except Exception as e:
    return {"status": "error", "message": str(e)}

Best Practices for Odoo REST API

1- Security

Never hardcode API keys in your frontend or mobile app code. Use environment variables or a secure vault. Restrict each API key to the minimum permissions the integration actually needs. Always use HTTPS, never HTTP.

2- Performance

Avoid fetching entire record sets when you only need a few fields. Filter on the server side and return only what the client needs. Cache frequently read data where possible to reduce load on your Odoo instance.

3- What Not To Do

Do not expose sensitive internal fields like account balances or employee salaries through a public-facing endpoint. Do not skip input validation and assume incoming data is always correct. Do not ignore error codes and just check whether a response arrived.

 Conclusion

The Odoo REST API format becomes much clearer once you see all the pieces together. Define your endpoints through controllers, structure your requests with the right headers and body, authenticate every call with your API key, and always handle errors gracefully. 

Whether you are building a mobile field app, syncing orders with a third-party platform, or creating a customer portal, this is the foundation you need to make it work reliably.

Ready to integrate Odoo REST API into your business systems? Contact us today for a free consultation and let our experts handle the setup for you.

Book Your Free Consultation