Skip to main content
Version: v0.25.0 (Latest)

Party REST API

The party model is managed over a REST surface mounted at /api/party/v1. Each party type has its own resource that creates, reads, lists, updates, and soft-deletes that one type and returns the typed object directly, a Person, an Organization, and so on, with no nested detail record to reassemble. A polymorphic /parties resource reads across all types, and further resources manage relationships, group membership, application login surfaces, and identity bindings.

Every endpoint is a thin HTTP adapter over an in-process service command. The HTTP layer decodes the request, calls the service command, and encodes the result; the business logic lives only in the service command. Each operation therefore has two command ids: a service id (party.<resource>.<action>) and a distinct REST id (party-rest.<resource>.<action>). The blocks below show each operation four ways, an abstract, the REST call, the in-process service command, and the gRPC envelope, so you can call it over whichever transport you use.

Every request runs within the caller's tenant, resolved from the OIDC bearer token; the tenant is never read from a client-supplied field. List endpoints accept both limit/offset and page/size, clamp the page size, and return a pagination block alongside the data array. Errors share a stable machine-readable body.

Quick Reference​

ResourceOperations
/personscreate, get, list, update, delete
/organizationscreate, get, list, update, delete
/organizationunitscreate, get, list, update, delete, list children, list members
/servicescreate, get, list, update, delete, get/set login config
/groupscreate, get, list, update, delete, list/replace/add/remove members
/partiespolymorphic get, polymorphic list, list a party's relationships
/relationshipscreate, get, list, update, delete
/identities/{identityId}/applications/{applicationId}get, set, delete binding

The blocks on this page cover a representative operation from each resource family. For the full set, see the Party Management reference.

Persons​

The person resource is the canonical example; every other typed resource follows the same five-operation shape.

Create​

Returns 201 Created with the full Person (server-assigned id, tenant from the session, and timestamps). A 400 is returned for a malformed body.

Supply the displayName and the optional name parts, birth date, origin, home organizationUnitId, and ownership. The result is the stored Person as one coherent object.

POST /api/party/v1/persons

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Get​

Returns 200 OK with the Person. The optional include set opts into associations such as specializations; by default nothing extra is hydrated. A 404 is returned when no person with that id exists in the tenant.

Reads one person by the id taken from the path. Pass include=specializations to hydrate the party's roles and validated attributes.

GET /api/party/v1/persons/{id}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

List​

Returns 200 OK with a page of Person objects. Narrow the page with the name and display-name filters, the home-unit and origin filters, and a free-text q; window it with limit/offset or page/size.

Lists the calling tenant's persons, paged and filtered. The tenant comes from the session; the result is a Page<Person> with a pagination block.

GET /api/party/v1/persons

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Update​

Returns 200 OK with the updated Person. A null or omitted field leaves the stored value unchanged. A 404 is returned when the person does not exist.

The id comes from the path. Supply only the fields to change; any null field keeps the current stored value.

PUT /api/party/v1/persons/{id}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Delete​

Soft-deletes the person and returns 204 No Content. A 404 is returned when the person does not exist.

Soft-deletes the person named by the path id. The command result reports whether a matching person existed and was deleted.

DELETE /api/party/v1/persons/{id}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Organizations​

Organizations follow the same five-operation shape as persons, returning the merged Organization object. The create block is shown; get, list, update, and delete mirror the person operations with the party.organization.* command ids.

Supply the legalName and the optional organization type, industry, contact details, and policy URIs. The result is the stored Organization.

POST /api/party/v1/organizations

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Registrations​

An organization carries its formal registrations, the registered numbers that prove the entity is who it claims to be, such as a VAT number, a Legal Entity Identifier, a DUNS number, or a Chamber of Commerce entry. They are managed through the organization's registrations sub-resource: list the registrations an organization holds, or add a new one as the entity is verified in a jurisdiction. These endpoints work directly against the organization store rather than through a separate service command, so they expose the Overview and API reference views only.

Lists the registrations held by the organization named by the path id. Each entry carries the registration type (the scheme), its value, and the issuing authority.

GET /api/party/v1/organizations/{id}/registrations

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Adds a registration to the organization named by the path id. Supply the registration type, the value, and the issuing authority.

POST /api/party/v1/organizations/{id}/registrations

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Organization Units​

An organization unit is created like any other party and additionally carries a parent unit, branding, and a terms URI. Beyond the standard five operations, a unit exposes GET /organizationunits/{id}/children to walk the nesting tree and GET /organizationunits/{id}/members to list the parties contained in it; both are in the full reference.

Supply the unit name, an optional parentOuId to nest it, and optional branding and terms. Omitting parentOuId places the unit directly under the tenant root.

POST /api/party/v1/organizationunits

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Services and Login Configuration​

A service is a software-backed party. A service that people sign in to additionally carries a login configuration set through PUT /services/{id}/login-config, which makes the service a login surface (see Identities and Identifiers).

Supply the displayName and the optional service type, endpoint URI, and OAuth client id. The result is the stored Service.

POST /api/party/v1/services

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

The id is the service party id. Supply the accepted authentication methods, the identifier types valid as logins here, the identity providers that may back login, and whether self-registration is allowed.

PUT /api/party/v1/services/{id}/login-config

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Identity Application Bindings​

An identity may authenticate at a service only through an explicit binding that grants the authenticable capability. Setting a binding ties an identity to an application with its allowed methods and an optional application role; deleting it removes the ability to log in there.

The identityId and applicationId come from the path. Supply the capabilities (such as authenticable), the allowed authentication methods, an optional application role, and the validity window.

PUT /api/party/v1/identities/{identityId}/applications/{applicationId}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Removes the binding between the identity and the application named in the path. The result reports whether a binding existed and was removed.

DELETE /api/party/v1/identities/{identityId}/applications/{applicationId}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Groups and Membership​

A group is created like any other party and gathers members. Membership is managed under /groups/{id}/members: list the members, replace the whole set, or add and remove one member at a time. A member may be any party, including another group.

Supply the group name. A group never bears specializations or attributes; it carries only its members.

POST /api/party/v1/groups

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

The id is the group and memberId is the party to add. The call is idempotent: adding a member that is already present is a no-op.

PUT /api/party/v1/groups/{id}/members/{memberId}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Addresses​

Any party can carry electronic addresses (email, phone, messaging handles) and physical addresses, attached as records under /parties/{id}/addresses. They are hydrated on demand rather than returned on every party read, so an ordinary read stays small and you ask for addresses only when you need them. The electronic-address create and list operations are shown; the physical-address operations and the per-address get, update, and delete follow the same shape under /parties/{id}/addresses/physical and are in the full reference.

The id is the owning party. Supply the address type, the value, and optional flags such as whether it is primary or already verified. The result is the stored ElectronicAddress.

POST /api/party/v1/parties/{id}/addresses/electronic

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Lists the electronic addresses attached to the party named by the path id.

GET /api/party/v1/parties/{id}/addresses/electronic

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Parties (Polymorphic)​

When you do not know a party's type in advance, the /parties resource reads across all types and returns the discriminated PartyEntity, the correct typed subclass for each row. GET /parties lists with filters on partyType, partySubtype, organizationUnitId, and origin; GET /parties/{id} reads one.

Reads one party by id regardless of type and returns it as the correct PartyEntity subclass. Use include to hydrate associations such as addresses.

GET /api/party/v1/parties/{id}

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Relationships​

Relationships are typed, directional edges between any two parties (see Relationships). Create them under /relationships, and list the relationships of a given party through /parties/{id}/relationships.

Supply the two party ids, the relationship type from the registered catalog (for example employed_by or same_entity), and an optional validity window. The result is the stored relationship.

POST /api/party/v1/relationships

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Lists every relationship in which the party named by the path id participates, in either direction, so you can walk the graph from one party to its counter-parties.

GET /api/party/v1/parties/{id}/relationships

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

Tenancy and Authorization​

Every endpoint operates in the single tenant resolved from the bearer token before the request reaches the adapter; the optional X-Tenant-ID header is a trusted-infrastructure override and is never used for ordinary access control. Reads are implicitly scoped to the caller's tenant, and writes land in the caller's tenant regardless of any tenant-shaped field in the payload.

Because each endpoint delegates to a named service command, authorization policies key on the command id (party.<resource>.<action>). A typical policy grants reads to any authenticated principal and restricts writes to administrators, and can layer in the RBAC, ABAC, and ReBAC rules that the party model itself supplies the facts for.