UDA endpoints — parties

How to call the party routes. The formal schema is the OpenAPI specification (openapi/source/connector/parties/); this page is the call contract. Internal processing is in the architecture reference; caveats in the implementation notes.

Every route except search requires a bearer token and party context (partyId); GET /v1/parties/search requires a bearer token only (it is not party-scoped). Path ids (relatedPartyId) are Ark party ids; scheduledPaymentId is the Ark scheduled-payment id.

Method	Path	Code	Purpose
GET	/v1/parties/search	200	Search CBS clients by individual name or company name
GET	/v1/parties	200	Get the caller's party profile
POST	/v1/parties	201	Create a party (individual / company / sole trader)
POST	/v1/parties/relationships	201	Add a party-to-party relationship to a company
PUT	/v1/parties	200	Update the caller's party
GET	/v1/parties/scheduled	200	List the party's scheduled payments
DELETE	/v1/parties/scheduled/{scheduledPaymentId}	204	Cancel a scheduled payment
GET	/v1/parties/relationships	200	List the party's relationships
DELETE	/v1/parties/relationships/{relatedPartyId}	204	Remove a relationship

Notes for callers

• Create (POST /v1/parties) accepts entityType INDIVIDUAL, COMPANY, or SOLE_TRADER (sole trader is treated as an individual with an ABN). TRUST / PARTNERSHIP are rejected (409). The connector selects a single email / phone / address per role from the arrays you send; much of the structured address detail and all phone metadata beyond the number are not forwarded to the core system (see the implementation notes). The response is { vendorId } (the core-system client key) — not a full party object.
• Create is not atomic. A failure partway can leave a created core-system client without a local mapping, or a created-but-not-finalised client (see the implementation notes). Retry/repair is the caller's responsibility.
• Add relationship takes relatedPartyId + relationshipType (DIRECTOR / SECRETARY / BENEFICIAL_OWNER / ULTIMATE_BENEFICIAL_OWNER / AUTHORIZED_REPRESENTATIVE / CONTACT_PERSON; others 400). The company is the partyId in context.
• Search is broad: an individual search matches on the first letter of the first name plus the last name, and results are returned without further name filtering (see the implementation notes). Supply either firstName+lastName (+ optional middleName) or name — the connector does not enforce this exclusivity itself. Each result carries vendorId, partyId (null if not provisioned in Ark), deleted, dateOfBirth, name.
• Get party returns the full profile; note it requires the core record to be complete (email, DOB, and addresses) or it fails with 500 (see the implementation notes).
• Cancel scheduled payment verifies the payment still exists in the core system and belongs to the party before deleting; the local delete and the core delete are transactional.

Errors

HTTP	Code	When
400	GEN000000	request body/params/query fail schema validation
400	PAR000010	unsupported relationshipType
403	PAR003003	cancel scheduled payment: the payment isn't owned by the party (SCHEDULED_PAYMENT_OWNERSHIP_VIOLATION)
404	PAR004001	no party mapping for the caller (ClientAuthManager.getClientKey → PARTY_NOT_FOUND); create: a relatedPartyId can't be resolved
404	PAR004007	cancel scheduled payment: no local scheduled-payment record
409	PAR009004	create/update: unsupported entityType (e.g. TRUST, PARTNERSHIP)
500	PAR100004/5	create: core system returned no entity number / client key
500	PAR100006/7	get party: core record is missing email / date of birth
500	PAR100008	search: the downstream search call failed
500	ACC* / PAY*	scheduled payments: an account, payment number, payment type, or interval couldn't be resolved
500	GEN100001	a relationship-operation ULTRACS fault (handleUltracsError falls back to DOWNSTREAM_CONNECTOR_ERROR since both relationship error maps are empty — see the implementation notes)