---
title: "AddPartyRequest"
url: "https://apiportal.pexaclear.com.au/apis/gap-au-aml-customer-experience-standard-v1-v1/versions/9c31c4c2-000c-418b-ad44-c201d75d8af9/schemas/AddPartyRequest"
---

> Full API specification: https://apiportal.pexaclear.com.au/apis/gap-au-aml-customer-experience-standard-v1-v1/versions/9c31c4c2-000c-418b-ad44-c201d75d8af9.md

# AddPartyRequest

Request to add parties (individual or entity) to an existing workspace. The parties field is an array to support adding multiple parties in a single request in future. Currently, exactly one party may be supplied per request — requests containing more than one party, or an empty array, are rejected with 400. Bulk addition (more than one party) is planned and will be enabled without any change to this contract.

## OpenAPI definition

```yaml
openapi: 3.0.3
info:
  title: AML Customer Experience API
  version: v1
servers:
  - url: https://api.pexaclear.com.au
    description: API Gateway URL
components:
  schemas:
    AddPartyRequest:
      type: object
      description: Request to add parties (individual or entity) to an existing
        workspace. The parties field is an array to support adding multiple
        parties in a single request in future. Currently, exactly one party may
        be supplied per request — requests containing more than one party, or an
        empty array, are rejected with 400. Bulk addition (more than one party)
        is planned and will be enabled without any change to this contract.
      required:
        - parties
      properties:
        parties:
          type: array
          description: List of parties to add to the workspace. Structured as an array to
            support adding multiple parties in a single request in future.
            Currently, exactly one party may be supplied per request — requests
            containing more than one party, or an empty array, are rejected with
            400. Bulk addition (more than one party) is planned and will be
            enabled without any change to this contract.
          items:
            oneOf:
              - description: "An individual party to add. The presence of organisationPartyId is
                  the sole discriminator between the two individual cases: when
                  provided, the individual is linked to that entity and role is
                  inherited; when omitted, the individual is standalone and role
                  is required."
                allOf:
                  - type: object
                    description: "Base fields shared by the add-party party variants. Discriminated
                      on partyType at the point of use: INDIVIDUAL adds a person
                      (standalone or entity-linked); ENTITY adds an
                      organisation."
                    required:
                      - partyType
                    properties:
                      partyType:
                        type: string
                        pattern: ^(INDIVIDUAL|ENTITY)$
                        description: "Party type. Allowed values: INDIVIDUAL, ENTITY."
                      role:
                        type: string
                        nullable: true
                        pattern: ^(BUYER|SELLER)$
                        description: "Party role. Required for a standalone individual and for an
                          entity. Ignored for an entity-linked individual, which
                          inherits the entity's role. Allowed values: BUYER,
                          SELLER."
                      externalPartyId:
                        type: string
                        maxLength: 50
                        nullable: true
                        description: Optional integrator-supplied identifier for this party. May be any
                          string value up to 50 characters (for example, an
                          identifier from your own system). If provided, it is
                          echoed back in the response so you can correlate your
                          party to the PEXA partyId.
                        example: cust123
                type: object
                required:
                  - partyType
                  - partySubType
                  - familyName
                  - countryCode
                  - mobileNumber
                  - email
                properties:
                  partyType:
                    type: string
                    pattern: ^(INDIVIDUAL)$
                  organisationPartyId:
                    type: string
                    format: uuid
                    nullable: true
                    description: References an existing ENTITY party on the workspace to link this
                      individual to; the linked individual inherits the entity's
                      role. Optional for a SELF individual (when omitted the
                      individual is standalone and role is required). Required
                      when partySubType is UBO — a UBO only exists under an
                      entity. Applies only to individuals.
                  partySubType:
                    type: string
                    pattern: ^(SELF|UBO)$
                    description: "Subtype of the individual party. Allowed values: SELF, UBO. Use
                      SELF for a standard individual (standalone or
                      entity-linked). Use UBO for an ultimate beneficial owner,
                      which must be linked to an entity (organisationPartyId is
                      required for UBO)."
                  firstName:
                    type: string
                    nullable: true
                    minLength: 1
                    maxLength: 50
                  middleNames:
                    type: string
                    nullable: true
                    minLength: 1
                    maxLength: 50
                  familyName:
                    type: string
                    minLength: 1
                    maxLength: 50
                  dateOfBirth:
                    type: string
                    format: date
                    nullable: true
                  countryCode:
                    type: string
                    minLength: 1
                    maxLength: 5
                    pattern: ^\+[0-9]{1,4}$
                    description: Country calling code, e.g. "+61"
                    example: "+61"
                  mobileNumber:
                    type: string
                    minLength: 8
                    maxLength: 20
                    pattern: ^[\d\s\-\+\(\)]{8,25}$
                    description: Must contain between 8 and 20 digits
                  email:
                    type: string
                    format: email
                    maxLength: 320
                    pattern: ^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$
                    description: Email address
              - description: An entity (organisation) party to add. Supports trusts, companies,
                  partnerships, government bodies, and other organisation types.
                  Shares the entity field set with workspace creation
                  (EntityPartyBase); validation mirrors workspace creation.
                allOf:
                  - type: object
                    description: "Base fields shared by the add-party party variants. Discriminated
                      on partyType at the point of use: INDIVIDUAL adds a person
                      (standalone or entity-linked); ENTITY adds an
                      organisation."
                    required:
                      - partyType
                    properties:
                      partyType:
                        type: string
                        pattern: ^(INDIVIDUAL|ENTITY)$
                        description: "Party type. Allowed values: INDIVIDUAL, ENTITY."
                      role:
                        type: string
                        nullable: true
                        pattern: ^(BUYER|SELLER)$
                        description: "Party role. Required for a standalone individual and for an
                          entity. Ignored for an entity-linked individual, which
                          inherits the entity's role. Allowed values: BUYER,
                          SELLER."
                      externalPartyId:
                        type: string
                        maxLength: 50
                        nullable: true
                        description: Optional integrator-supplied identifier for this party. May be any
                          string value up to 50 characters (for example, an
                          identifier from your own system). If provided, it is
                          echoed back in the response so you can correlate your
                          party to the PEXA partyId.
                        example: cust123
                  - description: Common entity (organisation) party fields shared by the
                      workspace-creation entity request and the add-party entity
                      request. Does not include the discriminator base fields
                      (partyType pattern / role), which differ per usage and are
                      supplied by the referencing schema.
                    type: object
                    required:
                      - entityName
                      - mainBusinessLocation
                      - partySubType
                      - servicingMode
                    properties:
                      partySubType:
                        type: string
                        pattern: ^(TRUST|BODY_CORPORATE_COMPANY|PARTNERSHIP_ASSOCIATION|GOVERNMENT_BODY|OTHER)$
                        description: "Organisation subtype. Allowed values: TRUST,
                          BODY_CORPORATE_COMPANY, PARTNERSHIP_ASSOCIATION,
                          GOVERNMENT_BODY, OTHER"
                      partySubTypeDescription:
                        type: string
                        nullable: true
                        minLength: 3
                        maxLength: 100
                        pattern: ^[a-zA-Z0-9 \-&/()]+$
                        description: Required when partySubType is OTHER. Must not be provided
                          otherwise.
                      servicingMode:
                        type: string
                        pattern: ^(SELF_SERVE|ASSISTED)$
                        description: "Servicing mode. Allowed values: SELF_SERVE, ASSISTED"
                      entityName:
                        type: string
                        minLength: 4
                        maxLength: 100
                      abn:
                        type: string
                        nullable: true
                        description: Australian Business Number (ABN) or Australian Company Number (ACN)
                      tradingName:
                        type: string
                        nullable: true
                        minLength: 1
                        maxLength: 100
                        description: Trading name or business name
                      mainBusinessLocation:
                        type: string
                        minLength: 6
                        maxLength: 8
                        pattern: ^[A-Z]{2,3} [0-9]{4}$
                        description: State and postcode in format 'STATE POSTCODE' (e.g. VIC 3000, NSW
                          2000)
                        example: VIC 3000
                      primaryContact:
                        nullable: true
                        allOf:
                          - type: object
                            description: Primary contact for ASSISTED servicing mode. Required when
                              servicingMode is ASSISTED.
                            required:
                              - familyName
                              - mobile
                              - email
                            properties:
                              firstName:
                                type: string
                                nullable: true
                                minLength: 1
                                maxLength: 50
                                description: First name of the primary contact
                              middleName:
                                type: string
                                nullable: true
                                minLength: 1
                                maxLength: 50
                                description: Middle name of the primary contact
                              familyName:
                                type: string
                                minLength: 1
                                maxLength: 50
                                description: Last name of the primary contact
                              mobile:
                                type: string
                                pattern: ^\+[1-9]\d{6,14}$
                                description: International mobile number
                                example: "+61400000000"
                              email:
                                type: string
                                format: email
                                maxLength: 320
                                pattern: ^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$
                                description: Email address
                        description: Required when servicingMode is ASSISTED. Contact details for the
                          primary person managing the entity verification.
                type: object
                required:
                  - partyType
                properties:
                  partyType:
                    type: string
                    pattern: ^(ENTITY)$
```
