Parties

How a party moves through its lifecycle, from the platform caller's perspective. For how to call each step see endpoints → parties.

A party is the tenant's record of a person or business in Ark. Its lifecycle is a small status machine; the onboarding detail differs a little by entity type:

• individual — a person.
• company — a business that can own relationships (its members).
• sole-trader — a sole trader.

Party status machine

A party has one of three statuses:

Status	Meaning
PROSPECT	Record created; provisioning not yet confirmed. A transient state during provisioning.
ACTIVE	Provisioned and activated; the party is usable.
TERMINATED	Soft-deleted; terminal.

Provisioning

POST /v1/parties/provision is the only call that drives a party to ACTIVE. In one request it creates the party record (PROSPECT), provisions it with the provider configured for your client/brand, and activates it (ACTIVE). The successful response always reports status: ACTIVE.

Provisioning runs more than one step and is safe to retry: if a later step doesn't complete, the party is still left ACTIVE and re-sending the same provision request reconciles it (the call is idempotent). You don't need to undo and recreate.

DELETE /v1/parties/{partyId} soft-deletes a party from either PROSPECT or ACTIVE to TERMINATED. There is no transition out of TERMINATED.

Entity-type support

Ark recognises five entity types; three are usable today:

Entity type	Provision / get / update / delete / search	Relationships	Status
INDIVIDUAL	✓	can be a member of a company	available
COMPANY	✓	owns relationships (members)	available
SOLE_TRADER	✓	—	available
TRUST	✗	—	planned
PARTNERSHIP	✗	—	planned

INDIVIDUAL, COMPANY, and SOLE_TRADER are accepted everywhere a party is created or read. TRUST and PARTNERSHIP are not yet supported — a request for one is rejected with 409 PAR009004 (INVALID_PARTY_TYPE) by parties.mapper.ts (3 throw sites); they are roadmap items, not a capability today.

Journey summary

1. Provision (POST /v1/parties/provision) — create + activate in one call (PROSPECT → ACTIVE).
2. Read / update (GET / PUT /v1/parties/{partyId}) — read or full-replace the party. Requires ACTIVE.
3. Relate (company only) — attach INDIVIDUAL members (company).
4. Terminate (DELETE /v1/parties/{partyId}) — soft-delete to TERMINATED.