Parties API

Party List

To view all parties, use the GET /api/parties/ REST API. It also supports pagination. The data is returned as a list of serialized party objects in the results key of response.

Common Party Fields

These fields are available for both individual and organizational parties:

Field	Type	Description	Example
number	str	The number (code) assigned to the party.	"1001"
party_type	str	Whether this party is an individual or an organization.	"individual" or "organization"
sub_type	str	More specific sub-types for parties. Optional. Accepted values are the codename values defined in PartySubType model of your instance.	"private_company"
role	str	The role of party in our system. Can be "none", "customer", "vendor", "employee", or "other". It can also be a combination of these roles.	"customer", "customer_and_vendor"
roles	list[str]	All roles of party as a list of strings. Custom roles are also included and returned with the codename of the role. This field if currently readonly, use role field for setting the role.	["customer", "vendor", "my_role"]
mobile	str	The main mobile number for this party. Any additional numbers are stored in the phones field.	"09121001234"
addresses	list[PartyAddress]	List of addresses for this party. Currently readonly. See Party Address for fields.	[{…}, {…}]
phones	list[PartyPhone]	List of phone numbers for this party. Currently readonly. This field is for storing any additional phone number the party as in addition to its main identifying mobile number that is stored in the mobile field. See Party Phone for fields.	[{…}, {…}]
notes	str	Any extra details for this party.	"VIP customer"

The necessary field names are written in bold. All other fields may be empty or null if the data is not available or not registered for the party.

Individual Party

If party is an individual (party_type="individual"), the result item also includes these fields:

Field	Type	Description	Example
first_name	str	Party's first name.	"Jane"
last_name	str	Party's last name.	"Doe"
national_code	str	The national code for this party.	"0021234001"

Organizational Party

If party is an organizational legal entity (party_type="organization"), the result item also includes these fields:

Field	Type	Description	Example
legal_name	str	Party's legally registered name.	"Example Corporation"
national_code	str	The national ID for this party.	"…"
economic_code	str	The economic code for this party.	"…"
registration_number	str	The registration number for this party.	"…"

Party Address

Each Address for a party (PartyAddress type) may include these fields:

Field	Type	Description	Example
address_type	str	Type of address like billing or shipping or office address.	"billing" or "shipping" or "office" or "other"
city	str	Name of the city of this address.	"تهران"
address	str	The address.	"خیابان آزادی، پلاک ۱"
postal_code	str	Postal code for the address.	"1344654114"
is_default	bool	Whether this address is the default address for the party. Defaults to false.	false
is_active	bool	Whether this address is active and valid for the party. Defaults to true.	true

Party Phone

Each phones for a party (PartyPhone type) may include these fields:

Field	Type	Description	Example
phone_type	str	Type of the phone like home or work phone. Defaults to "other".	"home" or "work" or "other_mobile" or "other"
phone	str	The phone number.	"02166017966"

Party Creation

To create a party, make POST request to the same endpoint with similar parameters. Make sure to pass the required fields of number and party_type. For easier access, try to fill all known fields for the party.

Bulk Operations

Use POST/PUT/PATCH /api/parties/bulk/ to create or update multiple parties in a single request. All operations accept a JSON array of party objects and execute atomically — if any item fails validation, no changes are saved.

Bulk Create

POST /api/parties/bulk/

Send a list of party objects (same fields as single creation). Returns 201 Created with the list of created parties.

[
  { "number": "2001", "party_type": "individual", "first_name": "Alice" },
  { "number": "2002", "party_type": "organization", "legal_name": "Example Corp" }
]

Bulk Full Update

PUT /api/parties/bulk/

Send a list of party objects. Each item must include number to identify the party to update. All writable fields are replaced (same semantics as single-party PUT). Returns 200 OK with the list of updated parties.

Bulk Partial Update

PATCH /api/parties/bulk/

Same as bulk PUT, but only the fields provided in each item are updated. Fields omitted from an item remain unchanged, including nested addresses and phones. Returns 200 OK with the list of updated parties.

Error Responses

If any item in the list is invalid (missing number, unknown number, or field validation failure), the endpoint returns 400 Bad Request with details about the first error found. No changes are persisted.