Implementation · Integration

How to integrate a mobile app with Odoo: architecture, APIs, and the gotchas we've hit

A practical guide to Odoo mobile app integration: the JSON-2 API vs JSON-RPC, authentication, backend-for-frontend patterns, real-time data, and the gotchas we've hit on real projects.

By Octagotech Team7 min readUpdated

Key takeaways

  • On Odoo 19 and later, use the JSON-2 API for CRUD and business methods alike. On older versions, use JSON-RPC. Both authenticate with API keys.
  • Authenticate with API keys under a dedicated Odoo user per integration, never an admin account.
  • Add a middleware layer only when you aggregate systems, handle poor connectivity, reshape data, or serve several apps.
  • For real-time updates, send Odoo webhooks to your server, then push to devices through FCM or APNs.

Mobile apps that talk to Odoo come up on many projects: a field technician app, a dispatch and proof-of-delivery app for drivers, a quoting app for sales reps. They usually start with the same question from the client: "Can our mobile app just talk directly to Odoo?" The answer is yes, with a few things to settle before you start. This post covers them.

One mobile app we built on Odoo is the driver app in our freight TMS: it texts drivers a tracking link, logs GPS on Google Maps and writes stop times back to the load in Odoo.

Odoo's API options, and which one to actually use

Odoo exposes more than one way to interact with it programmatically, and they are not equivalent.

XML-RPC is the oldest interface, served under the /xmlrpc/2 endpoints. You'll find it referenced in a lot of older Stack Overflow answers and community forum posts. Ignore it for new projects. It's verbose, and Odoo's documentation schedules XML-RPC and JSON-RPC for removal in Odoo 22.

JSON-RPC is the same external API carried over JSON, at the /jsonrpc endpoint. Every model and method Odoo supports is accessible through its object service: you call ORM methods (search_read, create, write, unlink) through execute_kw, pass domain filters in Odoo's domain syntax, and get back raw record dictionaries. Most existing integrations on Odoo 18 and earlier use it, and it is deprecated from Odoo 19. Don't confuse it with /web/dataset/call_kw, the endpoint the web client uses with a browser session: that one is internal and not meant for external apps.

JSON-2, new in Odoo 19 and continued in Odoo 20, is the API to use for new work. You POST a JSON object to /json/2/<model>/<method> with an API key in an Authorization: bearer <key> header, and the body carries the method's parameters by name, such as domain and fields for search_read. It reaches the same models and methods as JSON-RPC, so reading related records, triggering business logic and calling custom model methods all use the one endpoint shape. There is no session and no separate login call.

Our recommendation: on Odoo 19 and later, use JSON-2 for everything. On Odoo 18 and earlier, use JSON-RPC with API keys, and plan the move to JSON-2 for your next upgrade.

Authentication: API keys are the right answer now

Before API keys, the practical way to authenticate a programmatic client was a username and password, or a session cookie from /web/session/authenticate. This worked but had obvious problems for mobile: sessions expire, you're storing passwords on device, and every install has to re-authenticate.

API keys, available since Odoo 14, are now the correct way to authenticate non-browser clients. A user generates a key under Preferences → Account Security → New API Key; the key is tied to that user's access rights. With JSON-2 you send it as Authorization: bearer <key>; with JSON-RPC or XML-RPC you pass it in place of the password. Keys carry no session state and can be issued to a specific integration without sharing the user's login credentials. In current versions they also expire: Odoo does not allow a key to last longer than three months, so build key rotation into your deployment from the start.

A few things worth noting on the security side. API keys inherit the full permissions of the user they're created under; there's no native OAuth scope concept. This means you want to create a dedicated Odoo user for each integration with exactly the access groups that integration needs. A field technician app might need maintenance requests and device records, nothing else. A driver app might read delivery orders and write proof-of-delivery attachments, but not touch inventory valuations or accounting. Odoo's group-based access model is granular enough to do this well; the mistake is creating keys under an admin account because it's easier.

The temptation is to use an admin API key during development and clean it up later. Later never comes. Create the right user with the right groups from day one. It forces you to map out exactly what the mobile app needs.

Architecture: direct to Odoo vs. a middleware layer

Whether your mobile app should talk directly to Odoo or go through an intermediate layer (sometimes called a BFF, for backend-for-frontend) is a real architectural decision.

Direct integration is simpler, cheaper to build, and fine for many cases. If your mobile app is essentially a thin client for Odoo (field technicians updating maintenance records, sales reps creating quotes, warehouse staff confirming receipts), there's probably no need for middleware. The mobile app calls Odoo, gets records back, renders them.

A middleware layer starts making sense when any of these are true:

  • Your app needs to aggregate data from Odoo plus another system (a GPS provider, a payment processor, a third-party sensor platform).
  • The mobile client has poor connectivity and you want to handle retry logic, request queuing, and offline sync in one place rather than in every version of the mobile app.
  • You need to transform Odoo's data shape significantly before the mobile client can use it: flattening nested many-to-many structures, renaming fields, computing derived values.
  • Multiple mobile apps (iOS, Android, a web portal) need to call the same backend, and you don't want to duplicate Odoo integration logic in each.

As an example, take a field technician app that needs to combine Odoo maintenance records with a third-party charger or telematics API in a single request. Doing that aggregation on the mobile client is impractical. A middleware layer can handle the fan-out, cache device state, and give the mobile app a single clean endpoint. It also means the Odoo API key lives only on the server, never on user devices.

At the other end, a driver app that only ever needs Odoo data, for drivers with reliable mobile connectivity, can go direct. A middleware layer would add latency and an extra service to maintain for no real gain.

Real-time data: pushing Odoo events to mobile

Getting data out of Odoo on demand is straightforward. Getting Odoo to push events to a mobile app when something changes is harder, and there are a few different patterns depending on what version you're on and what you're trying to do.

Webhooks are available in Odoo 19 through automation rules: an automation rule can run a "Send Webhook Notification" action, so you pick the model, the trigger (record created, updated or deleted) and the URL to post to. When the event fires, Odoo sends an HTTP POST to your endpoint with data from the record. This is the cleanest pattern for server-to-server notification: your middleware or a push notification service receives the webhook and forwards to the mobile client via FCM or APNs. The limitation is that webhooks fire on ORM events, so if a status change is the result of a scheduled action rather than a direct write, you need to make sure the scheduled action actually triggers a write on the model you're watching.

Odoo's internal bus (the one the web client uses for live updates) is technically accessible but not designed for external consumption. It is fragile across Odoo upgrades and requires running a persistent connection, which has implications for mobile battery life and background execution. Treat it as a last resort.

Polling remains a valid fallback for many use cases. If your mobile app checks for updated delivery orders every 60 seconds, that's not a performance problem at any reasonable scale. Use search_read with a write_date domain filter so you only pull records that changed since your last sync timestamp. Keep it simple.

Key takeaway on real-time: Webhooks from automation rules are the right answer for server-side notification. For pushing to mobile devices, webhook → your server → FCM/APNs is a proven pattern. Don't try to maintain a persistent connection from a mobile app to Odoo's bus. It won't survive app backgrounding reliably.

Gotchas we've actually hit

Record rules will surprise you

Odoo's security model has two layers: access rights (what models a user can read/write) and record rules (which specific records within a model a user can see). Record rules are defined per model and can reference the current user, the user's company, or arbitrary field conditions. If your API user has the right access group but is hitting a record rule, search_read will silently return an empty result rather than an error. We've spent hours debugging "why is the mobile app getting zero records" only to find a multicompany record rule was filtering everything out. Check record rules early; don't assume an empty result means no data exists.

Load only the fields you need

Odoo models carry a lot of computed fields, related fields that trigger additional queries, and binary fields (attachments, images) that can be several megabytes. If you call search_read without a fields parameter, you get everything. On a mobile connection, loading a full stock.move record when you only need the product name, quantity, and state is wasteful and slow. Always pass an explicit fields list. This is one of the highest-impact performance improvements you can make and it's a two-minute fix.

Many-to-many fields return IDs, not values

When you read a many-to-many field through the API, Odoo returns a list of integer IDs by default. If your mobile app needs the names or other attributes of those related records, you need a second API call that reads them from the related model by ID. This is expected behavior, but it catches people off guard the first time. Plan for it in your data model and fetch related record details explicitly rather than assuming the API will denormalize for you.

Odoo's domain syntax requires exact field names

Domain filters use Odoo's internal field names, not display labels. partner_id, not "Customer". picking_type_code, not "Operation Type". When a filter silently returns wrong results, the first thing to check is whether you're using the Python field name as it appears in the model definition, not the string shown in the UI. The Odoo developer mode field inspector is your friend here.

Putting it together

Odoo is well suited to mobile integration. The API surface is comprehensive, the security model is flexible, and with Odoo 19's JSON-2 API straightforward use cases require very little boilerplate. The complexity is in the details: picking the right API for each operation, setting up authentication properly from the start, deciding whether you need a middleware layer, and understanding the quirks of how Odoo returns data.

None of these integrations is particularly difficult once you understand the patterns, but each is significantly harder if you start without a clear architecture decision.

If you're scoping a custom Odoo development project that involves a mobile component, we're happy to talk through the architecture before you start building. Book a discovery call to talk through what you're trying to build and where the complexity usually hides.

Talk through the architecture first

The first call takes 30 minutes.

Or email sales@octagotech.com