Odoo Field Types – General JSON API Guide

Odoo Field Types – General JSON API Guide​

This document references the expected JSON value format for all standard Odoo field types when constructing JSON payloads for the Odoo API (create, write, etc.).

1. Basic Field Types​

These fields accept simple, singular values.

Field Type	Description	Expected JSON Value	Example Value Only
char	Short text	String	Test Lead
text	Long text, multi-line	String	This is a long note
html	Rich text (HTML allowed)	String (HTML content)	<p><b>New Inquiry</b></p>
boolean	True/False flag	true or false	true
integer	Whole number	Number	25
float	Decimal number	Number	75.5
monetary	Decimal with currency	Number	1500.00
date	Date only (YYYY-MM-DD)	String	2025-11-01
datetime	Full date + time (UTC)	String (ISO 8601 format)	2025-10-31 09:30:00
selection	Single-choice dropdown	String (one of allowed internal values)	2

2. Relation Field Types​

These fields link to other records. The values for many2many and one2many are special Odoo command tuples.

Field Type	Description	Expected JSON Value	Example Value Only
many2one	Relation to a single record	ID (integer) of the linked record	45
many2many	Relation to multiple records	Odoo command tuples (list of lists)	[[6, 0, [1, 2, 3]]]
one2many	Relation to child records	Odoo command tuples (list of lists)	[[0, 0, {"product_id": 5, "qty": 2}]]

Odoo Command Syntax Reference​

Command	Meaning	Example Value Only (Tuple)
[0, 0, {values}]	Create new related record	[0, 0, {"name": "New Tag"}]
[1, ID, {values}]	Update existing related record	[1, 12, {"name": "Updated Tag"}]
[2, ID, 0]	Remove and Delete related record (from DB)	[2, 12, 0]
[3, ID, 0]	Unlink (Remove from relation, keep record in DB)	[3, 12, 0]
[4, ID, 0]	Link existing record	[4, 12, 0]
[5, 0, 0]	Remove all links (Equivalent to a mass unlink)	[5, 0, 0]
[6, 0, [IDs]]	Replace all with the given list of IDs	[6, 0, [1, 2, 3]]

3. Special Field Types​

These fields handle complex or non-standard data structures.

Field Type	Description	Expected JSON Value	Example Value Only
json	Structured JSON object	Object or JSON string	{"1": 2000, "2": 3000}
properties	Dynamic key-value pairs	Object	{"industry": "IT", "size": "SMB"}
reference	Link to any model	String "model_name,id"	calendar.event,15
many2one_reference	Similar to reference field	String "model,id"	crm.lead,10

4. Key Notes for API Users​

• Direct Key-Value: Send field names as keys and the expected value format as the value directly in the JSON body.
• Relations: many2one uses a simple integer ID. many2many and one2many require command tuples for any modifications to the linked records.
• Date/Time: Use ISO 8601 strings for both date (YYYY-MM-DD) and datetime (YYYY-MM-DD HH:MM:SS).
• Selection: Must use one of the allowed values (string), e.g., priority field with value "2".
• JSON/Properties: Accept nested objects directly.

---

5. Real-World Examples​

This section provides complete, ready-to-use JSON payload examples for common Odoo operations.

Example 1: Creating a CRM Lead​

Model: crm.lead

Operation: Create

{
"name": "Website Inquiry - John Doe",
"contact_name": "John Doe",
"email_from": "[email protected]",
"phone": "+1-555-0123",
"description": "Customer interested in Enterprise plan",
"type": "opportunity",
"priority": "2",
"user_id": 5,
"team_id": 3,
"tag_ids": [[6, 0, [1, 4, 7]]],
"expected_revenue": 15000.00,
"probability": 60.0,
"date_deadline": "2025-12-15"
}

Example 2: Creating a Helpdesk Ticket​

Model: helpdesk.ticket

Operation: Create

{
"name": "Unable to login to portal",
"partner_id": 123,
"team_id": 2,
"priority": "1",
"ticket_type_id": 5,
"description": "<p>Customer reports they cannot access their account after password reset.</p>",
"tag_ids": [[6, 0, [8, 12]]],
"sla_deadline": "2025-11-02 18:00:00"
}

Example 3: Updating a Sales Order​

Model: sale.order

Operation: Write (Update)

{
"state": "sale",
"commitment_date": "2025-11-15",
"order_line": [
[1, 45, {"product_uom_qty": 10}],
[0, 0, {
"product_id": 78,
"product_uom_qty": 5,
"price_unit": 150.00
}]
]
}

Example 4: Creating a Contact with Address​

Model: res.partner

Operation: Create

{
"name": "Acme Corporation",
"company_type": "company",
"email": "[email protected]",
"phone": "+1-555-9876",
"website": "https://acme.com",
"street": "123 Business Ave",
"city": "New York",
"state_id": 47,
"zip": "10001",
"country_id": 233,
"is_company": true,
"customer_rank": 1,
"category_id": [[6, 0, [2, 5]]]
}

Example 5: Creating an Invoice with Lines​

Model: account.move

Operation: Create

{
"move_type": "out_invoice",
"partner_id": 89,
"invoice_date": "2025-10-31",
"invoice_date_due": "2025-11-30",
"invoice_line_ids": [
[0, 0, {
"product_id": 34,
"quantity": 2,
"price_unit": 500.00,
"tax_ids": [[6, 0, [1]]]
}],
[0, 0, {
"product_id": 56,
"quantity": 1,
"price_unit": 1200.00,
"tax_ids": [[6, 0, [1]]]
}]
]
}

Example 6: Linking and Unlinking Many2many Records​

Model: project.task

Operation: Update tags

{
"tag_ids": [
[4, 10, 0],
[4, 15, 0],
[3, 8, 0]
]
}

Explanation: This links tags with IDs 10 and 15, and unlinks tag with ID 8.

---

Visual Reference​

[Image/Screenshot will be added here showing real API request/response examples]

---

6. Common Patterns & Tips​

Pattern 1: Replace All Related Records​

"tag_ids": [[6, 0, [1, 2, 3, 4]]]

This replaces all existing tags with the new list.

Pattern 2: Add Single Record to Many2many​

"tag_ids": [[4, 5, 0]]

This adds tag ID 5 without affecting existing tags.

Pattern 3: Create Child Records​

"order_line": [[0, 0, {"product_id": 10, "qty": 2}]]

This creates a new order line linked to the parent order.

Pattern 4: Update Existing Child Record​

"order_line": [[1, 25, {"qty": 5}]]

This updates the quantity of order line with ID 25.

---

This guide provides a complete reference for working with Odoo's JSON API across all standard field types and common use cases.