Odoo technical integration guide
For Odoo administrators, security reviewers and IT — how Revial authenticates with an API key, required access rights, API consumption, failure behaviour and auditing.
This guide describes what Revial does inside your Odoo database, so you can approve, configure and later audit the integration. For connecting see Connecting Revial to Odoo; for every field read and written see What Revial syncs with Odoo.
1. What you are approving
| Property | Value |
|---|---|
| API | Odoo external API over JSON-RPC (POST {instance}/jsonrpc) |
| Authentication | common.authenticate(database, login, API key), then object.execute_kw with the key |
| Access model | Delegated — Revial acts as the Odoo user who owns the API key |
| Odoo versions | 16, 17, 18 and 19 |
| Hosting | Any Odoo reachable at a public address (Odoo Online, Odoo.sh or self-hosted) |
| Admin rights | Not required |
Odoo plans to remove the /jsonrpc endpoint in Odoo 22; Revial will move to Odoo's
JSON-2 API before then.
2. What your admin has to do
| Situation | What to do |
|---|---|
| Always | Create an API key for the integration user (Preferences → Account Security) |
| You want a dedicated integration user | Create it with the CRM and contact access in section 4 |
| Self-hosted instance | Make it reachable at a public HTTPS address |
| You want Revial to write fields | Create the fields (or Properties), then map them in Revial |
| Another CRM is connected in Revial | Disconnect it — Odoo cannot be connected alongside another CRM |
3. Authentication and credentials
- What Revial stores: the instance URL, database name and login in plain text, and the API key encrypted at rest (AES-256-GCM). Odoo API keys do not expire in Revial; there is no refresh.
- Validation at connect: Revial checks the address is not a private, loopback or internal host, then authenticates with a 15-second timeout. Nothing is saved unless Odoo returns a user ID.
- Transport: Revial adds
https://when no scheme is given.http://is accepted, but sends the API key unencrypted — use HTTPS. - Rotation: connect again with the new key; Revial replaces the stored key and runs a full sync.
- Revocation: delete the API key in Odoo. Revial does not currently notify you when a key stops working — syncing stops until you reconnect.
Who may connect on the Revial side. An organisation owner or admin on a plan with the CRM integration; rate-limited. Odoo can only be connected when no other CRM is connected.
4. Required access rights
Revial uses these models as the key's user:
| Model | Operations |
|---|---|
res.partner | Read; write mapped fields; post chatter notes |
crm.lead | Read; write mapped fields |
crm.stage | Read |
mail.message | Read; create (meeting notes) |
ir.model.data | Look up the internal-note subtype |
ir.model.fields, properties.base.definition | Read (field-mapping screen) |
In practice this means a user with CRM access (for example Sales / CRM: User) who can read contacts and post in the chatter. Record rules apply: records the user cannot see are not synced.
Access errors are not skipped. If the user cannot read a model, that part of the sync fails and is retried; there is no partial result for that model. An access error when writing mapped fields fails the whole write.
5. What Revial reads and writes
Reads: companies and contacts (res.partner), opportunities (crm.lead of type
opportunity), stages, and chatter messages of type comment on those records.
Writes:
| Operation | Details |
|---|---|
| Meeting summary | mail.message create as an internal note (mail.mt_note) on the matched opportunity or partner |
| Mapped fields | write on the matched res.partner or crm.lead; Properties via read-merge-write |
Revial creates the message directly rather than calling message_post, so that the
HTML summary is not escaped. Revial never deletes records and never creates
partners, opportunities or activities.
6. Field mappings
Configured by organisation admins under Organization → CRM Settings → Property
Mapping. Mappable fields are writable scalar fields — char, text, HTML, integer,
float, monetary, boolean, date, datetime and selection — including Studio x_
fields and Odoo Properties. A failed batch write is retried field by field for
validation errors.
7. Sync cadence and API consumption
- Cadence: roughly every hour, starting immediately after connecting.
- Incremental:
write_dategreater than the previous sync. - Paging: 200 records per request, ordered by
write_date; there is no record cap, and all pages for a model are read in one job. - Order: companies → contacts → opportunities → notes.
- Timeouts: 30 seconds per request. There is no throttling or retry inside a job; failed jobs are retried by the queue.
- Deletions: archived records are picked up; deleted records are not detected.
8. Meeting-to-CRM matching
First match wins: direct IDs on the meeting; the open opportunity it is already linked to; attendee emails → contacts → opportunities (scored); company by website or email domain; company by name. Closed opportunities are excluded; free-email domains are ignored for company matching.
9. Security, limits and failure behaviour
- Least privilege: one user's API key; no admin rights.
- Network safety: private, loopback and internal addresses are refused.
- Secrets: the API key is encrypted at rest and never returned to the browser or written to logs.
- Brittle fields: Revial requests explicit field lists verified for Odoo 16–19; a field missing from a customised or future version stops that model's sync.
- Data storage: synced records and the raw API responses are stored in Revial and deleted when you disconnect.
10. Auditing and disconnecting
In Odoo: API keys are listed under the user's Account Security; notes posted by Revial appear in the chatter authored by that user.
To disconnect:
- In Revial — Disconnect on the Odoo card. Revial deletes its synced copy, the stored API key and the field mappings. It does not touch the key in Odoo.
- In Odoo — delete the API key or deactivate the user.
Notes Revial already posted stay in the chatter.
11. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| "Could not authenticate with Odoo…" | Wrong database, login or key | Check all three |
| "Could not reach the Odoo instance…" | Wrong URL, instance down, or not public | Check the URL is reachable from the internet |
| "That Odoo instance URL is not allowed." | Private or internal address | Use a public address |
| "Team already has an active CRM connection…" | Another CRM is connected | Disconnect it first |
| Records missing | User's access rights or record rules | Widen the user's access |
| Sync stopped with no message | API key deleted or user deactivated | Connect again with a new key |
| One model never syncs | Access error, or a field missing in your Odoo version | Check access rights; contact support |
What Revial syncs with Odoo
For your Odoo administrator and whoever reviews the integration's data access — every Odoo field Revial reads, everything it writes back, and the known gaps.
Connecting your Google Calendar
Read-only access to your primary Google calendar, connected in about 30 seconds — plus which meetings Revial then joins and prepares for.