Create Company Party in UDA Connector

This document is the exhaustive current-state mapping reference for entityType = COMPANY.

Read it together with the common create-party reference, which documents the common flow and common UDA fields shared by all supported create requests.

Request Field Coverage

Status meanings:

• direct: value is written to UDA
• selection only: value influences picker behavior or control flow but is not forwarded as its own UDA field
• ignored: value is accepted by the connector request contract but is not used in the current UDA create flow

Request field path	Status	UDA target / effect	Notes
entityType	selection only	Selects company mapper; results in AmlType = DCO and ClientType = Business	Must be COMPANY.
name	direct	Surname, Verification.Surname	Required. Not copied into AlternativeName — UDA rejects equal Surname/AlternativeName (see UDA Constraints below).
emailAddresses[].purpose	selection only	Chooses which email address is used	Current order prefers WORK, then HOME, then first available.
emailAddresses[].isPreferred	selection only	Chooses which email address is used	Preferred items win before non-preferred items.
emailAddresses[].address	direct	Contact.PhoneNumber[0].Number (tagged Category = EmailWork; signs as Contact[0])	One email only. Top-level Email is omitted — see UDA Constraints.
phoneNumbers[].purpose	selection only	Chooses which phone number is used	Current order prefers WORK, then MOBILE, then HOME, then first available.
phoneNumbers[].isPreferred	selection only	Chooses which phone number is used	Preferred items win before non-preferred items.
phoneNumbers[].countryCode	ignored	None	Current mapper uses fullNumber only.
phoneNumbers[].areaCode	ignored	None	Current mapper uses fullNumber only.
phoneNumbers[].number	ignored	None	Current mapper uses fullNumber only.
phoneNumbers[].extension	ignored	None	Current mapper uses fullNumber only.
phoneNumbers[].fullNumber	direct	PhoneNumbers[0].Number	Used only if a phone is provided and selected.
addresses[].purpose	selection only	Chooses business-style and mailing-style addresses	Business address prefers BUSINESS, then REGISTERED_OFFICE, then POSTAL; mailing address prefers REGISTERED_OFFICE, then POSTAL, then BUSINESS.
addresses[].isPreferred	selection only	Chooses business-style and mailing-style addresses	Preferred items win before non-preferred items.
addresses[].dpid	ignored	None	Required by schema, but not forwarded during current create.
addresses[].addressLine	direct	ResidentialAddress.Line1/Line2, MailingAddress.Line1/Line2, Verification.Address.Line1/Line2	Split at 32 characters.
addresses[].thoroughfareNumber1	ignored	None	Not forwarded during current create.
addresses[].thoroughfareNumber1Suffix	ignored	None	Not forwarded during current create.
addresses[].thoroughfareNumber2	ignored	None	Not forwarded during current create.
addresses[].thoroughfareNumber2Suffix	ignored	None	Not forwarded during current create.
addresses[].flatUnitType	ignored	None	Not forwarded during current create.
addresses[].flatUnitNumber	ignored	None	Not forwarded during current create.
addresses[].floorLevelType	ignored	None	Not forwarded during current create.
addresses[].floorLevelNumber	ignored	None	Not forwarded during current create.
addresses[].lotNumber	ignored	None	Not forwarded during current create.
addresses[].buildingName1	ignored	None	Not forwarded during current create.
addresses[].buildingName2	ignored	None	Not forwarded during current create.
addresses[].streetName	ignored	None	Not forwarded during current create.
addresses[].streetType	ignored	None	Not forwarded during current create.
addresses[].streetSuffix	ignored	None	Not forwarded during current create.
addresses[].postalDeliveryType	ignored	None	Not forwarded during current create.
addresses[].postalDeliveryNumber	ignored	None	Not forwarded during current create.
addresses[].postalDeliveryNumberPrefix	ignored	None	Not forwarded during current create.
addresses[].postalDeliveryNumberSuffix	ignored	None	Not forwarded during current create.
addresses[].localityName	direct	ResidentialAddress.Suburb, MailingAddress.Suburb, Verification.Address.Suburb	Taken from the selected addresses.
addresses[].postcode	direct	ResidentialAddress.Postcode, MailingAddress.Postcode, Verification.Address.Postcode	Taken from the selected addresses.
addresses[].state	direct	ResidentialAddress.State, MailingAddress.State, Verification.Address.State	Passed through directly.
addresses[].isCurrent	ignored	None	Not forwarded during current create.
addresses[].validFrom	ignored	None	Not forwarded during current create.
addresses[].validTo	ignored	None	Not forwarded during current create.
entityDetails.companyType	ignored	None	Required by schema, but not forwarded during current create.
entityDetails.incorporationDate	ignored	None	Required by schema, but not forwarded during current create.
entityDetails.jurisdiction	ignored	None	Required by schema, but not forwarded during current create.
entityDetails.authorizedCapital	ignored	None	Not forwarded during current create.
entityDetails.issuedCapital	ignored	None	Not forwarded during current create.
entityDetails.paidUpCapital	ignored	None	Not forwarded during current create.
entityDetails.isListed	ignored	None	Not forwarded during current create.
entityDetails.stockExchange	ignored	None	Not forwarded during current create.
entityDetails.tickerSymbol	ignored	None	Not forwarded during current create.
entityDetails.shareCapitalCurrency	ignored	None	Not forwarded during current create.
entityDetails.acn	direct	Acn	Direct mapping.
entityDetails.abn	direct	Abn	Direct mapping.
entityDetails.asicStatus	ignored	None	Not forwarded during current create.
entityDetails.gstRegistered	ignored	None	Not forwarded during current create.
entityDetails.gstRegistrationDate	ignored	None	Not forwarded during current create.
entityDetails.industryCode	direct	Occupation	Current company create uses industry code as UDA occupation.
entityDetails.industryDescription	ignored	None	Not forwarded during current create.
entityDetails.arkVerificationId	direct	VerificationDocuments[0].Fields[*]	Written as the configured verification reference field.
entityDetails.kyxVerificationDate	direct	VerificationDocuments[0].Fields[*]	Written as the configured verification date field.
relationships[].relationshipType	selection only	AddRelationship.Relationship.Code or error	Supported subset only; unsupported values fail before UDA writes.
relationships[].relatedPartyId	selection only	AddRelationship.Relationship.Id after lookup	Resolved to the related party's UDA CLIENT_NUMBER.
relationships[].ownershipPercentage	ignored	None	Accepted by schema but not forwarded during current create.
relationships[].votingRights	ignored	None	Accepted by schema but not forwarded during current create.
relationships[].isUltimateOwner	ignored	None	Accepted by schema but not forwarded during current create.
relationships[].effectiveFrom	ignored	None	Required by schema, but not forwarded during current create.
relationships[].effectiveTo	ignored	None	Accepted by schema but not forwarded during current create.

Enum and Selection Behavior

entityType

Request enum	Current UDA effect
COMPANY	AmlType = DCO, ClientType = Business

PhonePurpose

Current company phone selection order:

1. preferred WORK
2. preferred MOBILE
3. preferred HOME
4. any preferred phone
5. first WORK
6. first MOBILE
7. first HOME
8. first phone

Current important limitation:

• the selected phone purpose is not preserved in the outgoing UDA payload
• the outgoing UDA phone is always written as Type = B (Business), Location = WORK, IsHomeNumber = false, Category = LandlineWork — regardless of the request purpose
• this mapping is mandated by UDA: ClientType = Business rejects Mobile/Home phones with "Mobile Home is not applicable for Member class 'Business'", read-back of business clients filters to Type ∈ {B, F} (see mapOrganisationPartyDetails), and Category is rejected when absent with "'CATEGORY' field is mandatory"
• FAX is accepted by schema but only participates as a last-resort fallback candidate

EmailPurpose

Current company email selection order:

1. preferred WORK
2. preferred HOME
3. any preferred email
4. first WORK
5. first HOME
6. first email

There is no direct EmailPurpose -> UDA enum/code mapping in current company create.

AddressPurpose

Current company business-address selection order:

1. preferred BUSINESS
2. preferred REGISTERED_OFFICE
3. preferred POSTAL
4. any preferred address
5. first BUSINESS
6. first REGISTERED_OFFICE
7. first POSTAL
8. first address

Current company mailing-address selection order:

1. preferred REGISTERED_OFFICE
2. preferred POSTAL
3. preferred BUSINESS
4. any preferred address
5. first REGISTERED_OFFICE
6. first POSTAL
7. first BUSINESS
8. first address

There is no direct AddressPurpose -> UDA enum/code mapping in current company create.

Current test-backed behavior notes:

• preferred BUSINESS wins for the business / verification address even when a preferred REGISTERED_OFFICE is also present
• preferred REGISTERED_OFFICE wins for the mailing address even when a preferred BUSINESS address is also present
• if no addressLine is supplied, the mapper does not synthesize one from structured address parts; the resulting UDA Line1 remains undefined

CompanyType

All CompanyType enum values are currently validation-only at connector create time. They do not map to a UDA field in the current implementation.

RelationshipType

Current supported relationship mappings:

Request enum	Current UDA code	Confidence	Notes
DIRECTOR	OFF	Medium	Based on local Bruno / UDA references.
SECRETARY	SEC	High	Direct local UDA match.
BENEFICIAL_OWNER	BNO	High	Direct local UDA match.
ULTIMATE_BENEFICIAL_OWNER	BNO	Medium	Reuses BNO; no clearer local UDA code found.
AUTHORIZED_REPRESENTATIVE	BBA	Low	Local UDA references do not cleanly prove this semantic mapping.
CONTACT_PERSON	REL	Low	Local UDA references are generic.

Current request-enum values accepted by schema but rejected by connector create:

• SHAREHOLDER
• CHAIRMAN
• CEO
• CFO
• COO
• MANAGER
• TRUSTEE
• BENEFICIARY
• SETTLOR
• APPOINTOR
• GUARDIAN
• GENERAL_PARTNER
• LIMITED_PARTNER
• MANAGING_PARTNER
• POWER_OF_ATTORNEY
• LEGAL_GUARDIAN
• EXECUTOR
• ADMINISTRATOR
• GUARANTOR

Those currently fail with Unsupported company relationship type before any downstream UDA write.

Company-Specific UDA Fields

These fields are added on top of the common fields documented in the common create-party reference.

UDA field	Current source / value	Notes
Abn	entityDetails.abn	Direct mapping when present.
Acn	entityDetails.acn	Direct mapping when present.
AlternativeName	Not set	Omitted from the SOAP envelope. See UDA Constraints below.
AmlType	Hardcoded DCO	Selected by entityType = COMPANY.
ClientType	Hardcoded Business	Selected by entityType = COMPANY.
Contact	Selected request email, if any, tagged Category = EmailWork	See UDA Constraints below.
GivenNames	undefined	Company create does not populate personal given names.
PhoneNumbers	Selected request phone, if any	See UDA Constraints below.
Surname	name	UDA surname is reused for the company name.
Verification.Address	Selected business-style address	Same mapped value as the chosen business address.
Verification.Surname	name	Current company verification payload uses the company name.
VerificationDocuments.VerificationDocument[0].Document	createPartyConfig.idReferenceDocumentId	Configuration-driven document ID.
VerificationDocuments.VerificationDocument[0].Fields[*].FieldId	createPartyConfig.idReferenceDocumentDateId, createPartyConfig.idReferenceDocumentReferenceId	Configuration-driven field IDs.
VerificationDocuments.VerificationDocument[0].Fields[*].FieldValue	kyxVerificationDate, arkVerificationId	Date is formatted as dd MMM yyyy UTC and uppercased.
VerificationProfiles.ClientVerificationProfile	Hardcoded current business profile set	See IDs below.

Current business verification profile IDs:

• 36 = Australia
• 181 = ''
• 183 = ''
• 184 = 0
• 185 = 0
• 186 = ''
• 187 = ''
• 188 = ''
• 356 = ''

UDA Constraints for ClientType = Business

UDA enforces extra validation on the AddClient payload when the client is a business. These constraints shape how the mapper builds the SOAP envelope:

AlternativeName must not equal Surname

UDA rejects an AddClient (or UpdateClient) call where Surname and AlternativeName carry the same non-empty value with:

Name and Alternate / Additional Name cannot be the same.

The connector's company creation contract has no separate alternative-name source field (SchemasCompanyPartyCreationRequestACU exposes only a top-level name), so the mapper omits AlternativeName from the create payload entirely. On update, the previous AlternativeName returned by GetClient is carried forward unchanged via the base spread in mapBaseUpdateClientRequest, so the same equality check never trips.

Phone Type / Location must match the member class

UDA rejects business clients with a Mobile/Home phone:

Mobile Home is not applicable for Member class 'Business'.

The individual create path uses Type=M + Location=HOME + IsHomeNumber=true, which is valid only for ClientType = Individual (member class IND). For ClientType = Business (member class DCO), the connector must instead emit Type=B (Business) + Location=WORK + IsHomeNumber=false. This matches what GetClient returns for business clients, where mapOrganisationPartyDetails filters phones with Type ∈ {B, F}.

Phone Category is mandatory

UDA rejects an AddClient payload whose PhoneNumbers[*] is missing the Category field:

'CATEGORY' field is mandatory.

Category is the UDA ContactCategory enum (WSDL: LandlineWork, LandlineHome, MobileWork, MobileHome, FaxWork, FaxHome, LandlineInternational, FaxInternational, MobileInternational, EmailWork, EmailPersonal, LinkedIn, FacebookIM). The connector request does not distinguish landline vs. mobile, so each helper sets a fixed value:

• individual create (mapIndividualCreatePhoneNumbers) → Category = 'MobileHome'
• company create (mapCompanyCreatePhoneNumbers) → Category = 'LandlineWork'

These constraints are enforced by two dedicated helpers in party.mapper.ts — mapIndividualCreatePhoneNumbers and mapCompanyCreatePhoneNumbers. Do not reuse the individual helper from the company path.

Email must be tagged Category = EmailWork and carried via Contact (with a signing-path rewrite)

UDA rejects business clients whose email is classified as EmailPersonal:

Email Personal is not applicable for Member class 'Business'.

The top-level Email field on AddClientRequest is a plain xs:string, but UDA derives a ContactCategory from it server-side and defaults to EmailPersonal on ClientType = Business — the same category the validator then rejects. Providing an additional explicit Contact entry with Category = 'EmailWork' is not sufficient on its own: the auto-tagging on the top-level Email still fires, and the request is still rejected.

The company path therefore:

1. omits the top-level Email field entirely (mapCommonAddClientRequest is called without an email argument from mapCompanyAddClientRequest); and
2. populates the AddClientRequest.Contact slot — in the wrapped { PhoneNumber: [{ … }] } shape that matches the WSDL tns:ArrayOfPhoneNumber — with a single entry tagged Category = 'EmailWork', Type = 'Email', Location = 'WORK', Number = <email address>, plus IsHomeNumber: false, IsPreferredContact: true, IsVerified: true, When = 'AnyTime'. All eight fields must be populated — UDA's signature template lists every one and any omission breaks validation. The helper is mapCompanyCreateEmailContact.

Auth-token signing path needs a Contact.PhoneNumber → Contact rewrite

UDA's request-token signature is computed by walking the request object and hashing each leaf at its JSON path. UDA's signature template expects Contact[N].<Field> (array-indexed, no PhoneNumber wrapper), but the JS request shape — matching the WSDL — produces Contact.PhoneNumber[N].<Field> when walked. Without a rewrite, the server reports:

The token signature does not match what was calculated. … Contact[0].Category was expected but not found. … (MISSING) Computed is missing property Contact.PhoneNumber[0].Category.

The fix lives in the ultracs-connector-client library (src/clients/client.ts) — the addClient function declares a replacementPaths array that the signing layer applies to each path before hashing. A Contact.PhoneNumber → Contact rule has been added, mirroring the existing PhoneNumbers.PhoneNumber → PhoneNumbers rule (which is why the PhoneNumbers slot already works without any shape divergence). With the rewrite in place, walked paths like Contact.PhoneNumber[0].Category are signed as Contact[0].Category, matching UDA's template.

Consequence for read-back: getClientResponse.Email in mapOrganisationPartyDetails continues to surface the email when UDA returns it (UDA stores the email regardless of which field carried it on write). Do not reuse mapCompanyCreateEmailContact for the individual path — EmailPersonal is the correct (and accepted) default there, and the individual create still emits the top-level Email.

AddRelationship Payload

For each resolved requested relationship, the connector sends:

UDA field	Current source / value	Notes
Metadata.SessionId	Operator session	From StartSession.
Metadata.AuthorisationClaim	Operator session	From StartSession.
Metadata.ClientKey	Created company ClientKey	Added after AddClient succeeds.
ClientNumber	Created company CLIENT_NUMBER	Added after AddClient succeeds.
Relationship.Code	Mapped from relationshipType	Uses the mapping table above.
Relationship.Id	Related party's resolved UDA CLIENT_NUMBER	Looked up from Ark's stored connector mapping.
Relationship.Type	Hardcoded C	Current create always sends Type = C.

Current relationship behavior:

• if relationships is omitted or empty, the company is still created and no relationship lookup or UDA AddRelationship call happens
• requested relationships are resolved before the operator session starts
• the same related party can appear multiple times and is sent once per requested role
• UDA receives one AddRelationship call per requested relationship, in request order
• a related party must already exist in Ark and already have a stored UDA CLIENT_NUMBER

Connector Response

Current company create success response from the connector:

• coreSystemReference = createdClient.clientKey

The connector does not return a richer company-specific response body here. Platform later adds partyId, status, vendorId, and connectorName around the connector result.

Fields Accepted But Not Currently Forwarded To UDA

The following request data is currently accepted by the connector create request contract but never written into any UDA create payload:

• phoneNumbers[].countryCode
• phoneNumbers[].areaCode
• phoneNumbers[].number
• phoneNumbers[].extension
• addresses[].dpid
• all address structure fields except addressLine, localityName, postcode, and state
• addresses[].isCurrent
• addresses[].validFrom
• addresses[].validTo
• entityDetails.companyType
• entityDetails.incorporationDate
• entityDetails.jurisdiction
• entityDetails.authorizedCapital
• entityDetails.issuedCapital
• entityDetails.paidUpCapital
• entityDetails.isListed
• entityDetails.stockExchange
• entityDetails.tickerSymbol
• entityDetails.shareCapitalCurrency
• entityDetails.asicStatus
• entityDetails.gstRegistered
• entityDetails.gstRegistrationDate
• entityDetails.industryDescription
• relationships[].ownershipPercentage
• relationships[].votingRights
• relationships[].isUltimateOwner
• relationships[].effectiveFrom
• relationships[].effectiveTo

Current Risks and Open Questions

• a large part of the company request schema is currently validation-only rather than integration-effective: companyType, incorporationDate, jurisdiction, capital fields, listing fields, asicStatus, gst*, and industryDescription are all accepted but ignored
• the request shape therefore suggests broader company support than the current UDA create mapping actually provides
• phone semantics are lossy: the request phone purpose is discarded; the outgoing UDA phone is always written with the business-class metadata (Type=B, Location=WORK, IsHomeNumber=false) required by UDA for ClientType = Business
• address semantics are lossy: the create flow keeps only addressLine, localityName, postcode, and state, and drops the rest of the structured address model
• structured addresses without addressLine are especially risky: the mapper does not synthesize Line1 from structured fields, so a schema-valid request can still produce a sparse UDA address payload
• relationship-code semantics are not equally well evidenced: AUTHORIZED_REPRESENTATIVE -> BBA, CONTACT_PERSON -> REL, and ULTIMATE_BENEFICIAL_OWNER -> BNO remain the weakest current assumptions
• the platform schema accepts many relationship types that the connector create path still rejects at runtime
• company create is not transactional across Ark mapping persistence and downstream UDA writes: AddClient can succeed before later UpdateClient or AddRelationship failure leaves partial state behind
• AddRelationship response handling is still a sensitivity point: the WSDL allows Messages to be absent, so callers must not assume a populated message list
• the required verification fields arkVerificationId and kyxVerificationDate are forwarded, but the platform does not currently own a full company KYB initiation path