---
title: "Add Participant Reference"
url: "https://developer.pexa.co.uk/apis/workspace-v1-v1/versions/32819e5a-6411-493b-abe8-00b7c7ca6c77/operations/addReference"
---

> Full API specification: https://developer.pexa.co.uk/apis/workspace-v1-v1/versions/32819e5a-6411-493b-abe8-00b7c7ca6c77.md

# Add Participant Reference

`POST` `/partner/api/platformconnect/v1/workspaces/{workspace_id}/references`

Operation ID: `addReference`

This API allows the user to add a reference number to the workspace

## Path parameters

- `workspace_id` (string, uuid, required) - Workspace id

## Header parameters

- `X-Request-Correlation-Id` (string, optional)

## Request body

Content types: `application/json`

## Responses

- `200` - OK
- `400` - BAD REQUEST
- `500` - INTERNAL SERVER ERROR
- `503` - SERVICE UNAVAILABLE

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Workspace
  version: v1.3.0
servers:
  - url: https://api.pexa.co.uk
    description: API Gateway URL
paths:
  /partner/api/platformconnect/v1/workspaces/{workspace_id}/references:
    post:
      tags:
        - Reference
      summary: Add Participant Reference
      description: This API allows the user to add a reference number to the workspace
      operationId: addReference
      security:
        - oauth2:
            - add:law_firm_reference
            - add:legal_representation_details
      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:
                - referenceNumber
                - representativeRole
              properties:
                referenceId:
                  type: string
                  format: uuid
                  readOnly: true
                representativeId:
                  type: string
                  format: uuid
                referenceNumber:
                  maxLength: 25
                  minLength: 1
                  type: string
                  example: "123456"
                representativeRole:
                  type: string
                  pattern: ^(BORROWER_REPRESENTATIVE|INCOMING_LENDER|INCOMING_LENDER_REPRESENTATIVE|WORKSPACE_LAW_FIRM|BUYER_REPRESENTATIVE|OUTGOING_PROPRIETOR_REPRESENTATIVE)$
                  example: BORROWER_REPRESENTATIVE
                  description: >
                    Representative role: [`BORROWER_REPRESENTATIVE`,
                    `INCOMING_LENDER`, `INCOMING_LENDER_REPRESENTATIVE`,
                    `WORKSPACE_LAW_FIRM`, `BUYER_REPRESENTATIVE`,
                    `OUTGOING_PROPRIETOR_REPRESENTATIVE`] <br> Note -
                    Representative role `WORKSPACE_LAW_FIRM` will be replaced
                    with `INCOMING_LENDER_REPRESENTATIVE` soon
      responses:
        "200":
          description: OK
          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:
                  - referenceNumber
                  - representativeRole
                properties:
                  referenceId:
                    type: string
                    format: uuid
                    readOnly: true
                  representativeId:
                    type: string
                    format: uuid
                  referenceNumber:
                    maxLength: 25
                    minLength: 1
                    type: string
                    example: "123456"
                  representativeRole:
                    type: string
                    pattern: ^(BORROWER_REPRESENTATIVE|INCOMING_LENDER|INCOMING_LENDER_REPRESENTATIVE|WORKSPACE_LAW_FIRM|BUYER_REPRESENTATIVE|OUTGOING_PROPRIETOR_REPRESENTATIVE)$
                    example: BORROWER_REPRESENTATIVE
                    description: >
                      Representative role: [`BORROWER_REPRESENTATIVE`,
                      `INCOMING_LENDER`, `INCOMING_LENDER_REPRESENTATIVE`,
                      `WORKSPACE_LAW_FIRM`, `BUYER_REPRESENTATIVE`,
                      `OUTGOING_PROPRIETOR_REPRESENTATIVE`] <br> Note -
                      Representative role `WORKSPACE_LAW_FIRM` will be replaced
                      with `INCOMING_LENDER_REPRESENTATIVE` soon
        "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
              example:
                errors:
                  - field: reference-number
                    message: incorrect data type
        "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
              example:
                errors:
                  - message: Internal Server Error
        "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:
      - add:law_firm_reference
      - add:legal_representation_details
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
```