---
title: "Add Parties to an Existing Workspace"
url: "https://apiportal.pexaclear.com.au/apis/gap-au-aml-customer-experience-standard-v1-v1/versions/9c31c4c2-000c-418b-ad44-c201d75d8af9/operations/addParty"
---

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

# Add Parties to an Existing Workspace

`POST` `/api/experience/v1/workspaces/{workspaceId}/parties`

Operation ID: `addParty`

Add one or more parties to an existing workspace. A party may be an individual or an entity (organisation). The request and response are array-shaped to accommodate future bulk party addition without a contract change. At present a single party per request is supported; supplying more than one party, or none, returns 400. An individual may be standalone (organisationPartyId omitted; role required) or linked to an existing entity party on the workspace (organisationPartyId provided; role inherited from the entity). An entity is added with its own role. Added parties undergo the same IDV/compliance verification flow as parties supplied at workspace creation.

## Path parameters

- `workspaceId` (string, uuid, required) - Identifier of the workspace to add the party to

## Request body (required)

Content types: `application/json`

## Responses

- `201` - Party added successfully
- `400` - Bad request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not found
- `422` - Unprocessable entity - request payload failed validation
- `500` - Internal server error
- `501` - Not implemented - the requested functionality is not yet available

## 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
paths:
  /api/experience/v1/workspaces/{workspaceId}/parties:
    post:
      summary: Add Parties to an Existing Workspace
      operationId: addParty
      tags:
        - Verification
      description: Add one or more parties to an existing workspace. A party may be an
        individual or an entity (organisation). The request and response are
        array-shaped to accommodate future bulk party addition without a
        contract change. At present a single party per request is supported;
        supplying more than one party, or none, returns 400. An individual may
        be standalone (organisationPartyId omitted; role required) or linked to
        an existing entity party on the workspace (organisationPartyId provided;
        role inherited from the entity). An entity is added with its own role.
        Added parties undergo the same IDV/compliance verification flow as
        parties supplied at workspace creation.
      security:
        - oauth2:
            - x-api:add:parties
      parameters:
        - name: workspaceId
          in: path
          required: true
          description: Identifier of the workspace to add the party to
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              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)$
            examples:
              StandaloneBuyer:
                summary: Add a standalone individual buyer
                value:
                  parties:
                    - partyType: INDIVIDUAL
                      partySubType: SELF
                      role: BUYER
                      familyName: Smith
                      firstName: Jane
                      dateOfBirth: 1990-05-20
                      countryCode: "+61"
                      mobileNumber: 412345678
                      email: jane.smith@example.com
              EntityLinkedIndividual:
                summary: Add an individual linked to an existing entity
                value:
                  parties:
                    - organisationPartyId: b2c3d4e5-f6a7-8901-bcde-f12345678901
                      partyType: INDIVIDUAL
                      partySubType: SELF
                      familyName: Smith
                      firstName: John
                      dateOfBirth: 1985-03-10
                      countryCode: "+61"
                      mobileNumber: 498765432
                      email: john.smith@example.com
              EntityLinkedUbo:
                summary: Add a UBO (ultimate beneficial owner) linked to an existing entity
                value:
                  parties:
                    - organisationPartyId: b2c3d4e5-f6a7-8901-bcde-f12345678901
                      partyType: INDIVIDUAL
                      partySubType: UBO
                      familyName: Taylor
                      firstName: Mary
                      dateOfBirth: 1978-11-22
                      countryCode: "+61"
                      mobileNumber: "0411222333"
                      email: mary.taylor@example.com
              EntitySelfServe:
                summary: Add a self-serve entity (trust)
                value:
                  parties:
                    - partyType: ENTITY
                      role: BUYER
                      entityName: Smith Family Trust
                      partySubType: TRUST
                      servicingMode: SELF_SERVE
                      mainBusinessLocation: VIC 3000
                      abn: "53004085616"
                      tradingName: Smith Investments
              EntityAssisted:
                summary: Add an assisted entity (company, with primary contact)
                value:
                  parties:
                    - partyType: ENTITY
                      role: SELLER
                      entityName: Acme Holdings Pty Ltd
                      partySubType: BODY_CORPORATE_COMPANY
                      servicingMode: ASSISTED
                      mainBusinessLocation: NSW 2000
                      abn: "51824753556"
                      primaryContact:
                        firstName: John
                        familyName: Smith
                        mobile: "+61400000000"
                        email: john@acmeholdings.com.au
              EntityOther:
                summary: Add an entity of subtype OTHER (description required)
                value:
                  parties:
                    - partyType: ENTITY
                      role: BUYER
                      entityName: Special Purpose Vehicle Ltd
                      partySubType: OTHER
                      partySubTypeDescription: Managed Investment Scheme
                      servicingMode: SELF_SERVE
                      mainBusinessLocation: NSW 2000
      responses:
        "201":
          description: Party added successfully
          content:
            application/json:
              schema:
                type: object
                description: Response for the add-party request. The workspaceId is returned
                  once at the top level as it is common to all parties. The
                  parties array mirrors the request order; it currently contains
                  a single element, matching the one-party-per-request limit.
                required:
                  - workspaceId
                  - parties
                properties:
                  workspaceId:
                    type: string
                    format: uuid
                    description: Identifier of the workspace the parties were added to
                  parties:
                    type: array
                    description: Parties created by this request, in the same order as the request.
                      Currently contains a single element, mirroring the
                      one-party-per-request limit.
                    items:
                      type: object
                      properties:
                        partyId:
                          type: string
                          format: uuid
                          description: Identifier of the newly created party
                        partyType:
                          type: string
                          enum:
                            - INDIVIDUAL
                            - ENTITY
                          description: "Party type of the added party. Allowed values: INDIVIDUAL,
                            ENTITY."
                        role:
                          type: string
                          enum:
                            - BUYER
                            - SELLER
                          nullable: true
                          description: "Role of the added party. Allowed values: BUYER, SELLER."
                        organisationPartyId:
                          type: string
                          format: uuid
                          nullable: true
                          description: Present only for entity-linked individuals; the entity party this
                            individual is linked to
                        externalPartyId:
                          type: string
                          maxLength: 50
                          nullable: true
                          description: The integrator-supplied identifier echoed from the request for this
                            party. Null when no externalPartyId was supplied.
                        partyDetails:
                          type: object
                          additionalProperties: true
                          description: The submitted party details echoed back (e.g. names, contact,
                            entity information), so the returned party is
                            self-describing and can be matched to the party you
                            submitted.
              examples:
                StandaloneResponse:
                  summary: Standalone individual added
                  value:
                    workspaceId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    parties:
                      - partyId: d4e5f6a7-b8c9-0123-def4-567890123456
                        partyType: INDIVIDUAL
                        role: BUYER
                EntityLinkedResponse:
                  summary: Entity-linked individual added
                  value:
                    workspaceId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    parties:
                      - partyId: e5f6a7b8-c9d0-1234-ef56-7890abcdef12
                        partyType: INDIVIDUAL
                        role: BUYER
                        organisationPartyId: b2c3d4e5-f6a7-8901-bcde-f12345678901
                EntityResponse:
                  summary: Entity added
                  value:
                    workspaceId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    parties:
                      - partyId: f6a7b8c9-d0e1-2345-f678-90abcdef1234
                        partyType: ENTITY
                        role: BUYER
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
        "422":
          description: Unprocessable entity - request payload failed validation
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
        "501":
          description: Not implemented - the requested functionality is not yet available
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        field:
                          type: string
security:
  - oauth2:
      - x-api:add:parties
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.pexa-group.com.au/oauth/token
          scopes:
            x-api:initiate:verifications: Permission to initiate verifications
            x-api:add:parties: Permission to add parties to an existing workspace
```
