The parties module serves parties and their photos, addresses, communication channels and channel types, person languages, and the reference data for countries, address levels, and address level values. All 53 endpoints sit under /api/v1/parties. For business meaning see the Parties module page.
Group facts¶
| Item | Value | Source |
|---|---|---|
| Base path | /api/v1/parties |
src/cluster_erp/core/module_base.py:37-38, src/cluster_erp/modules/parties/module.py:96 |
| Routers | 5 router objects in 5 files; listed in the section Endpoint summary | src/cluster_erp/modules/parties/module.py:76 |
| Endpoints | 53, counted from the route decorators and add_api_route calls of the routers that register_routes mounts |
src/cluster_erp/modules/parties/addresses/routes.py, src/cluster_erp/modules/parties/communication_channels/routes.py, src/cluster_erp/modules/parties/parties/routes.py ... |
| Authentication | Bearer header or session cookie, resolved by get_current_user; see Authentication and headers |
src/cluster_erp/modules/auth/guards.py:85-167 |
| Permission guard | 53 of 53 routes declare require_permission |
src/cluster_erp/modules/auth/guards.py:205-240 |
| App entitlement gate | require_app("parties") on every mounted router |
src/cluster_erp/modules/parties/module.py:103 |
| Error format | JSON body {"error": {...}}; see Errors |
src/cluster_erp/server/error_handler.py:33-46 |
Endpoint summary¶
One row per sub-module folder. The router prefix is added to the base path.
| Sub-module | Routers | Endpoints | Router source |
|---|---|---|---|
settings |
router (/settings) |
18 | src/cluster_erp/modules/parties/settings/routes.py:30 |
parties |
router |
9 | src/cluster_erp/modules/parties/parties/routes.py:28 |
addresses |
router |
7 | src/cluster_erp/modules/parties/addresses/routes.py:21 |
communication_channels |
router |
13 | src/cluster_erp/modules/parties/communication_channels/routes.py:27 |
person_languages |
router |
6 | src/cluster_erp/modules/parties/person_languages/routes.py:19 |
Countries and address levels endpoints¶
Countries (with an update from the internet and an address level seed), address levels, and address level values.
| Method | Path | Handler | Permission | Request | Query | Response | Status | Source |
|---|---|---|---|---|---|---|---|---|
GET |
/api/v1/parties/settings/countries/ |
list_countries |
country.read |
none | active_only |
list[CountryRead] |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:38 |
POST |
/api/v1/parties/settings/countries/update-from-internet |
update_countries_from_internet |
country.create |
none | none | dict |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:55 |
POST |
/api/v1/parties/settings/countries/ |
create_country |
country.create |
CountryCreate |
none | CountryRead |
201 |
src/cluster_erp/modules/parties/settings/routes.py:65 |
GET |
/api/v1/parties/settings/countries/{country_id} |
get_country |
country.read |
none | none | CountryRead |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:79 |
PUT |
/api/v1/parties/settings/countries/{country_id} |
update_country |
country.update |
CountryUpdate |
none | CountryRead |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:92 |
POST |
/api/v1/parties/settings/countries/bulk-delete |
bulk_delete_countries |
country.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:106 |
DELETE |
/api/v1/parties/settings/countries/{country_id} |
delete_country |
country.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/settings/routes.py:117 |
POST |
/api/v1/parties/settings/countries/{country_id}/seed-address-levels |
seed_address_levels |
country.seed |
none | none | dict |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:133 |
GET |
/api/v1/parties/settings/countries/{country_id}/address-levels |
list_address_levels |
address_level.read |
none | none | list[AddressLevelRead] |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:154 |
POST |
/api/v1/parties/settings/address-levels |
create_address_level |
address_level.create |
AddressLevelCreate |
none | AddressLevelRead |
201 |
src/cluster_erp/modules/parties/settings/routes.py:171 |
PUT |
/api/v1/parties/settings/address-levels/{level_id} |
update_address_level |
address_level.update |
AddressLevelUpdate |
none | AddressLevelRead |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:182 |
POST |
/api/v1/parties/settings/address-levels/bulk-delete |
bulk_delete_address_levels |
address_level.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:196 |
DELETE |
/api/v1/parties/settings/address-levels/{level_id} |
delete_address_level |
address_level.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/settings/routes.py:207 |
GET |
/api/v1/parties/settings/address-levels/{level_id}/values |
list_address_level_values |
address_level_value.read |
none | parent_id |
list[AddressLevelValueRead] |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:223 |
POST |
/api/v1/parties/settings/address-level-values |
create_address_level_value |
address_level_value.create |
AddressLevelValueCreate |
none | AddressLevelValueRead |
201 |
src/cluster_erp/modules/parties/settings/routes.py:238 |
PUT |
/api/v1/parties/settings/address-level-values/{value_id} |
update_address_level_value |
address_level_value.update |
AddressLevelValueUpdate |
none | AddressLevelValueRead |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:249 |
POST |
/api/v1/parties/settings/address-level-values/bulk-delete |
bulk_delete_address_level_values |
address_level_value.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/settings/routes.py:266 |
DELETE |
/api/v1/parties/settings/address-level-values/{value_id} |
delete_address_level_value |
address_level_value.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/settings/routes.py:277 |
Parties endpoints¶
Party records and the party photo. The router has no prefix, so party paths sit directly under the module base path.
| Method | Path | Handler | Permission | Request | Query | Response | Status | Source |
|---|---|---|---|---|---|---|---|---|
GET |
/api/v1/parties/ |
list_parties |
party.read |
none | search, party_type, role, active_only, limit, offset |
dict |
200 (default) | src/cluster_erp/modules/parties/parties/routes.py:37 |
POST |
/api/v1/parties/ |
create_party |
party.create |
PartyCreate |
none | PartyRead |
201 |
src/cluster_erp/modules/parties/parties/routes.py:70 |
GET |
/api/v1/parties/{party_id} |
get_party |
party.read |
none | none | PartyRead |
200 (default) | src/cluster_erp/modules/parties/parties/routes.py:88 |
PUT |
/api/v1/parties/{party_id} |
update_party |
party.update |
PartyUpdate |
none | PartyRead |
200 (default) | src/cluster_erp/modules/parties/parties/routes.py:105 |
POST |
/api/v1/parties/bulk-delete |
bulk_delete_parties |
party.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/parties/routes.py:123 |
DELETE |
/api/v1/parties/{party_id} |
delete_party |
party.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/parties/routes.py:135 |
GET |
/api/v1/parties/{party_id}/photo |
get_party_photo |
party.read |
none | none | Response |
200 (default) | src/cluster_erp/modules/parties/parties/routes.py:161 |
POST |
/api/v1/parties/{party_id}/photo |
set_party_photo |
party.update |
multipart file |
none | PartyRead |
200 (default) | src/cluster_erp/modules/parties/parties/routes.py:187 |
DELETE |
/api/v1/parties/{party_id}/photo |
delete_party_photo |
party.update |
none | none | none | 204 |
src/cluster_erp/modules/parties/parties/routes.py:233 |
Addresses endpoints¶
Addresses of a party and a list of all addresses.
| Method | Path | Handler | Permission | Request | Query | Response | Status | Source |
|---|---|---|---|---|---|---|---|---|
GET |
/api/v1/parties/addresses/all |
list_all_addresses |
address.read |
none | search, limit, offset, party_id, address_type |
dict |
200 (default) | src/cluster_erp/modules/parties/addresses/routes.py:29 |
GET |
/api/v1/parties/{party_id}/addresses |
list_addresses |
address.read |
none | search |
list[AddressRead] |
200 (default) | src/cluster_erp/modules/parties/addresses/routes.py:92 |
POST |
/api/v1/parties/{party_id}/addresses |
create_address |
address.create |
AddressCreate |
none | AddressRead |
201 |
src/cluster_erp/modules/parties/addresses/routes.py:104 |
GET |
/api/v1/parties/addresses/{address_id} |
get_address |
address.read |
none | none | AddressRead |
200 (default) | src/cluster_erp/modules/parties/addresses/routes.py:119 |
PUT |
/api/v1/parties/addresses/{address_id} |
update_address |
address.update |
AddressUpdate |
none | AddressRead |
200 (default) | src/cluster_erp/modules/parties/addresses/routes.py:132 |
POST |
/api/v1/parties/addresses/bulk-delete |
bulk_delete_addresses |
address.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/addresses/routes.py:146 |
DELETE |
/api/v1/parties/addresses/{address_id} |
delete_address |
address.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/addresses/routes.py:157 |
Communication channels endpoints¶
Channel types with a seed of defaults, the channels of a party, and a list of all channels.
| Method | Path | Handler | Permission | Request | Query | Response | Status | Source |
|---|---|---|---|---|---|---|---|---|
POST |
/api/v1/parties/settings/channel-types/seed-defaults |
seed_channel_type_defaults |
channel_type.seed |
none | none | dict |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:35 |
GET |
/api/v1/parties/settings/channel-types/ |
list_channel_types |
channel_type.read |
none | active_only |
list[ChannelTypeRead] |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:44 |
POST |
/api/v1/parties/settings/channel-types/ |
create_channel_type |
channel_type.create |
ChannelTypeCreate |
none | ChannelTypeRead |
201 |
src/cluster_erp/modules/parties/communication_channels/routes.py:61 |
PUT |
/api/v1/parties/settings/channel-types/{type_id} |
update_channel_type |
channel_type.update |
ChannelTypeUpdate |
none | ChannelTypeRead |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:72 |
POST |
/api/v1/parties/settings/channel-types/bulk-delete |
bulk_delete_channel_types |
channel_type.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:86 |
DELETE |
/api/v1/parties/settings/channel-types/{type_id} |
delete_channel_type |
channel_type.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/communication_channels/routes.py:97 |
GET |
/api/v1/parties/channels/all |
list_all_channels |
channel.read |
none | search, limit, offset |
dict |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:113 |
GET |
/api/v1/parties/{party_id}/channels |
list_channels |
channel.read |
none | none | list[CommunicationChannelRead] |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:158 |
POST |
/api/v1/parties/{party_id}/channels |
create_channel |
channel.create |
CommunicationChannelCreate |
none | CommunicationChannelRead |
201 |
src/cluster_erp/modules/parties/communication_channels/routes.py:169 |
GET |
/api/v1/parties/channels/{channel_id} |
get_channel |
channel.read |
none | none | CommunicationChannelRead |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:184 |
PUT |
/api/v1/parties/channels/{channel_id} |
update_channel |
channel.update |
CommunicationChannelUpdate |
none | CommunicationChannelRead |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:197 |
POST |
/api/v1/parties/channels/bulk-delete |
bulk_delete_channels |
channel.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/communication_channels/routes.py:214 |
DELETE |
/api/v1/parties/channels/{channel_id} |
delete_channel |
channel.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/communication_channels/routes.py:225 |
Person languages endpoints¶
Languages of a person party.
| Method | Path | Handler | Permission | Request | Query | Response | Status | Source |
|---|---|---|---|---|---|---|---|---|
GET |
/api/v1/parties/{party_id}/languages |
list_languages |
person_language.read |
none | none | list[PersonLanguageRead] |
200 (default) | src/cluster_erp/modules/parties/person_languages/routes.py:22 |
POST |
/api/v1/parties/{party_id}/languages |
create_language |
person_language.create |
PersonLanguageCreate |
none | PersonLanguageRead |
201 |
src/cluster_erp/modules/parties/person_languages/routes.py:33 |
GET |
/api/v1/parties/languages/{language_id} |
get_language_row |
person_language.read |
none | none | PersonLanguageRead |
200 (default) | src/cluster_erp/modules/parties/person_languages/routes.py:45 |
PUT |
/api/v1/parties/languages/{language_id} |
update_language |
person_language.update |
PersonLanguageUpdate |
none | PersonLanguageRead |
200 (default) | src/cluster_erp/modules/parties/person_languages/routes.py:58 |
POST |
/api/v1/parties/languages/bulk-delete |
bulk_delete_languages |
person_language.bulk_delete |
BulkDeleteRequest |
none | BulkDeleteResponse |
200 (default) | src/cluster_erp/modules/parties/person_languages/routes.py:72 |
DELETE |
/api/v1/parties/languages/{language_id} |
delete_language |
person_language.delete |
none | none | none | 204 |
src/cluster_erp/modules/parties/person_languages/routes.py:83 |
Error codes¶
The table lists the error codes that code under src/cluster_erp/modules/parties/ raises, found by a syntax-tree scan for AppError(...), the factories in src/cluster_erp/core/errors.py (not_found, conflict, protected, permission_denied, privilege_escalation, check_version), and HTTPException(...). A status of 400 is the AppError default (src/cluster_erp/core/errors.py:23). Guard errors (401, 403), the entitlement codes, and validation errors (422) apply to every route and are listed on Errors.
| Code | HTTP status | Raised in | First site |
|---|---|---|---|
RESOURCE_CONFLICT |
409 |
settings |
src/cluster_erp/modules/parties/settings/routes.py:74 |
RESOURCE_NOT_FOUND |
404 |
addresses, communication_channels, parties, person_languages, settings |
src/cluster_erp/modules/parties/addresses/routes.py:115 |
VALIDATION_ERROR |
400 |
parties |
src/cluster_erp/modules/parties/parties/routes.py:198 |
Events emitted¶
The table lists the contract classes that code under src/cluster_erp/modules/parties/ passes directly to EventBus.emit, found by a syntax-tree scan. Events built in a variable first are not counted. The contracts are described in Contracts reference.
| Contract | Sites | First site |
|---|---|---|
PartyCreated |
1 | src/cluster_erp/modules/parties/parties/services.py:156 |
PartyDeleted |
2 | src/cluster_erp/modules/parties/parties/services.py:222 |
PartyUpdated |
1 | src/cluster_erp/modules/parties/parties/services.py:202 |
Related pages¶
Verified against commit 92f8051 on 2026-11-13.