--- title: "Add Party Representation" url: "https://developer.pexa.co.uk/apis/workspace-v1-v1/versions/f42817f3-815f-4a74-8ba5-2f83efd8ab42/operations/addPartyRepresentation" --- > Full API specification: https://developer.pexa.co.uk/apis/workspace-v1-v1/versions/f42817f3-815f-4a74-8ba5-2f83efd8ab42.md # Add Party Representation `POST` `/partner/api/platformconnect/v1/workspaces/{workspace_id}/representation` Operation ID: `addPartyRepresentation` Add legal representation details for a party in a workspace ## Path parameters - `workspace_id` (string, uuid, required) - Workspace id ## Header parameters - `X-Request-Correlation-Id` (string, optional) ## Request body (required) Content types: `application/json` ## Responses - `202` - Accepted - Party representation request queued for async processing - `400` - BAD REQUEST - `401` - UNAUTHORIZED - `403` - FORBIDDEN - `404` - NOT FOUND - `500` - INTERNAL SERVER ERROR - `503` - SERVICE UNAVAILABLE ## OpenAPI definition ```yaml openapi: 3.0.1 info: title: Workspace version: v1 servers: - url: https://api.pexa.co.uk description: API Gateway URL paths: /partner/api/platformconnect/v1/workspaces/{workspace_id}/representation: post: tags: - PartyRepresentation summary: Add Party Representation description: Add legal representation details for a party in a workspace operationId: addPartyRepresentation security: - oauth2: - x-api:add:legal_representation_details - add:legal_representation_details - edit:workspace_parties - add:law_firm_reference - add:workspace_participants parameters: - in: header name: X-Request-Correlation-Id schema: type: string description: The unique identifier for the request - name: workspace_id in: path description: Workspace id required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object required: - partyId - representedBy properties: partyId: type: string format: uuid description: The unique identifier of the party representedBy: type: string pattern: ^(PEXA_SUBSCRIBER_LAW_FIRM|EXTERNAL_LAW_FIRM|NOT_REPRESENTED)$ description: > Type of legal representation: * `PEXA_SUBSCRIBER_LAW_FIRM` - Represented by a PEXA subscriber law firm (subscriber ID extracted from JWT token) * `EXTERNAL_LAW_FIRM` - Represented by an external (non-PEXA subscriber) law firm * `NOT_REPRESENTED` - Not represented (requires verification of identity) externalLawFirm: type: object required: - name - address properties: name: type: string minLength: 1 maxLength: 160 description: External law firm name address: type: object required: - postcode properties: name: maxLength: 50 minLength: 0 type: string example: 1 The House number: maxLength: 4 minLength: 0 type: string example: 123a flat: maxLength: 30 minLength: 0 type: string example: Flat 32 street: maxLength: 60 minLength: 0 type: string example: Huddersfield town: maxLength: 30 minLength: 0 type: string example: West Yorkshire postcode: maxLength: 8 minLength: 6 type: string example: M16 0RA pattern: ^(([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9][A-Za-z]?))))\s[0-9][A-Za-z]{2}))$ representationId: type: string format: uuid description: Existing representation ID to reuse (for external law firms only) referenceNumber: type: string minLength: 1 maxLength: 18 pattern: ^[a-zA-Z0-9\/\-\\?:().,'#=!"%&*<>;@{+\s]*$ description: Reference number for the representation (required for external law firms when not reusing) verificationOfIdentity: type: string pattern: ^(LAW_FIRM_CERTIFIED|IDENTITY_EVIDENCE)$ example: LAW_FIRM_CERTIFIED description: | Allowed values: [`LAW_FIRM_CERTIFIED`, `IDENTITY_EVIDENCE`] examples: PEXASubscriberLawFirm: value: partyId: a1b2c3d4-e5f6-7890-1234-567890abcdef representedBy: PEXA_SUBSCRIBER_LAW_FIRM summary: Add PEXA Subscriber Law Firm Representation (subscriber ID extracted from JWT token) ExternalLawFirm: value: partyId: b2c3d4e5-f6a7-8901-2345-678901bcdefg representedBy: EXTERNAL_LAW_FIRM externalLawFirm: name: Smith & Partners LLP address: number: "123" street: High Street town: London postcode: SW1A 1AA referenceNumber: EXT789012 summary: Add External Law Firm Representation NotRepresented: value: partyId: c3d4e5f6-a7b8-9012-3456-789012cdefgh representedBy: NOT_REPRESENTED verificationOfIdentity: LAW_FIRM_CERTIFIED summary: Add Not Represented with Verification of Identity ReuseExternalLawFirm: value: partyId: d4e5f6a7-b8c9-0123-4567-890123defghi representedBy: EXTERNAL_LAW_FIRM representationId: repr-ext-law-123 summary: Reuse Existing External Law Firm Representation required: true responses: "202": description: Accepted - Party representation request queued for async processing headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object required: - workspaceId - partyId properties: workspaceId: type: string format: uuid description: The workspace ID partyId: type: string format: uuid description: The party ID representationId: type: string format: uuid description: Representation ID (for EXTERNAL_LAW_FIRM types only) representedBy: type: string description: Type of representation enum: - EXTERNAL_LAW_FIRM - PEXA_SUBSCRIBER_LAW_FIRM - NOT_REPRESENTED subscriberId: type: string format: uuid description: Subscriber ID (for PEXA_SUBSCRIBER_LAW_FIRM only) externalLawFirm: description: External law firm details (for NEW EXTERNAL_LAW_FIRM only) type: object required: - name - address properties: name: type: string minLength: 1 maxLength: 160 description: External law firm name address: type: object required: - postcode properties: name: maxLength: 50 minLength: 0 type: string example: 1 The House number: maxLength: 4 minLength: 0 type: string example: 123a flat: maxLength: 30 minLength: 0 type: string example: Flat 32 street: maxLength: 60 minLength: 0 type: string example: Huddersfield town: maxLength: 30 minLength: 0 type: string example: West Yorkshire postcode: maxLength: 8 minLength: 6 type: string example: M16 0RA pattern: ^(([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9][A-Za-z]?))))\s[0-9][A-Za-z]{2}))$ verificationOfIdentity: type: string description: Verification of identity method (for NOT_REPRESENTED only) examples: newExternal: summary: NEW external law firm value: workspaceId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 partyId: 3fa85f64-5717-4562-b3fc-2c963f66afa7 representationId: 3fa85f64-5717-4562-b3fc-2c963f66afa8 representedBy: EXTERNAL_LAW_FIRM externalLawFirm: name: Smith & Partners LLP address: name: Suite 100 number: "1" street: King Street town: Manchester postcode: M2 4LQ existingExternal: summary: EXISTING external law firm value: workspaceId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 partyId: 3fa85f64-5717-4562-b3fc-2c963f66afa7 representationId: 3fa85f64-5717-4562-b3fc-2c963f66afa8 representedBy: EXTERNAL_LAW_FIRM pexaSubscriber: summary: PEXA subscriber law firm value: workspaceId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 partyId: 3fa85f64-5717-4562-b3fc-2c963f66afa7 representedBy: PEXA_SUBSCRIBER_LAW_FIRM subscriberId: 3fa85f64-5717-4562-b3fc-2c963f66afa9 notRepresented: summary: NOT_REPRESENTED value: workspaceId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 partyId: 3fa85f64-5717-4562-b3fc-2c963f66afa7 representedBy: NOT_REPRESENTED verificationOfIdentity: LAW_FIRM_CERTIFIED "400": description: BAD REQUEST headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message "401": description: UNAUTHORIZED headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message "403": description: FORBIDDEN headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message "404": description: NOT FOUND headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message "500": description: INTERNAL SERVER ERROR headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message "503": description: SERVICE UNAVAILABLE headers: X-API-Version: schema: type: string description: The API version that was used to process the request. X-Request-Correlation-Id: schema: type: string description: The unique identifier for the request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string description: Field message: type: string description: Error message example: errors: - message: Service under maintenance security: - oauth2: - x-api:add:legal_representation_details - add:legal_representation_details - edit:workspace_parties - add:law_firm_reference - add:workspace_participants components: securitySchemes: oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://login.pexauk.co.uk/oauth/token scopes: x-api:create:purchase_workspaces: Permission to create purchase workspace x-api:create:remortgage_workspaces: Permission to create remortgage workspace x-api:cancel:workspaces: Permission to cancel the workspace add:law_firm_reference: add law firm reference add:legal_representation_details: add legal representation details view:workspaces: view workspace create:title_change_request: create title change request edit:workspace_parties: edit workspace parties x-api:add:legal_representation_details: Permission to add party representation x-api:edit:external_law_firm_details: Permission to update external law firm representation create:workspaces: Permission to create workspaces edit:workspaces: Permission to edit workspaces edit:lodgement_proprietors: Permission to edit proprietors linked to lodgement case view:lodgement_proprietors: Permission to view proprietors linked to lodgement case add:workspace_participants: Permission to add workspace participants edit:external_law_firm_details: Permission to edit external law firm details edit:law_firm_reference: Permission to edit law firm reference ```