> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert a participant document

> Assign a customer-scoped Commenda file to one participant document slot. This request creates or replaces the typed participant document in one transaction without changing the reusable file. Repeating the request with the same fileId is safe.

Assigns a customer-scoped Commenda file to one participant document slot.

Use this endpoint after uploading a customer file with the Commenda OS Partner API. Commenda creates or replaces the typed participant document in one transaction without changing the reusable file. There is no separate file registration call.

If you are starting from a passport scan, utility bill, or other local file, first follow [Upload files for incorporation](/engine/incorporation/partner-incorporation-document-upload-flow) to upload the file and get a `file.fileId`.

The slot is replacement-based by `participantId` and `documentKind`. Calling this endpoint again with a different `fileId` replaces the file for that participant document. Calling it again with the same `fileId` is safe.

The `documentKind` path value comes from the incorporation requirements. Current values include `PASSPORT_SCAN` and `UTILITY_BILL`.

```json theme={null}
{
  "fileId": 456
}
```


## OpenAPI

````yaml PUT /partner/incorporation/{incorporationId}/participants/{participantId}/documents/{documentKind}
openapi: 3.0.1
info:
  title: Commenda Public APIs
  description: >-
    APIs for Commenda entity management, partner incorporation, indirect tax,
    compliance, and corporate operations.
  license:
    name: NONE
    url: NONE
  version: 1.0.0
servers:
  - url: https://api.prod.commenda.io/api/v1
    description: Commenda platform APIs, including Partner Incorporation and Commenda OS.
  - url: https://transaction-tax.api.in.commenda.io/api/v1
    description: Global Indirect Tax API.
security:
  - bearerAuth: []
paths:
  /partner/incorporation/{incorporationId}/participants/{participantId}/documents/{documentKind}:
    put:
      summary: Upsert a participant document
      description: >-
        Assign a customer-scoped Commenda file to one participant document slot.
        This request creates or replaces the typed participant document in one
        transaction without changing the reusable file. Repeating the request
        with the same fileId is safe.
      operationId: upsertPartnerIncorporationParticipantDocument
      parameters:
        - name: incorporationId
          in: path
          required: true
          schema:
            type: string
          description: Incorporation identifier returned by create or list endpoints.
        - name: participantId
          in: path
          required: true
          schema:
            type: string
          description: >-
            Incorporation-specific participant identifier returned by register,
            list, or read endpoints.
        - name: documentKind
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
          description: Typed document requirement to satisfy for this participant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerUpsertParticipantDocumentRequest'
      responses:
        '200':
          description: Participant document upserted successfully
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PartnerIncorporationParticipantDocumentMutationResponse
        '400':
          description: >-
            Malformed participant document payload, incompatible file type, or
            document kind not required for this participant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '403':
          description: Incorporation is not accessible to the partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
        '404':
          description: Incorporation, participant, or file not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePublicError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    PartnerIncorporationDocumentKind:
      type: string
      description: Type of document linked to an incorporation participant.
      enum:
        - PASSPORT_SCAN
        - UTILITY_BILL
    PartnerUpsertParticipantDocumentRequest:
      type: object
      required:
        - fileId
      properties:
        fileId:
          type: integer
          description: >-
            Existing customer-scoped Commenda file id to assign to the
            participant document slot.
          example: 456
      example:
        fileId: 456
    PartnerIncorporationParticipantDocumentMutationResponse:
      type: object
      required:
        - document
        - incorporationValidation
      properties:
        document:
          $ref: '#/components/schemas/PartnerIncorporationParticipantDocument'
        incorporationValidation:
          $ref: '#/components/schemas/PartnerIncorporationValidationSummary'
    AffiliatePublicError:
      type: object
      required:
        - statusCode
        - message
        - error
      properties:
        statusCode:
          type: integer
          example: 403
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Company does not belong to this affiliate firm
        error:
          type: string
          example: Forbidden
    PartnerIncorporationParticipantDocument:
      type: object
      required:
        - documentId
        - participantId
        - documentKind
        - fileId
        - status
      properties:
        documentId:
          type: string
          description: Identifier for this participant document link.
          example: document_123
        participantId:
          type: string
          description: Participant this document belongs to.
          example: participant_123
        documentKind:
          $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
        fileId:
          type: integer
          description: Commenda file satisfying this document requirement.
          example: 456
        status:
          $ref: '#/components/schemas/PartnerIncorporationParticipantDocumentStatus'
    PartnerIncorporationValidationSummary:
      type: object
      required:
        - isComplete
        - missingRequirements
        - invalidRequirements
      properties:
        isComplete:
          type: boolean
          description: >-
            True when the current intake state satisfies the current
            incorporation requirements and is eligible to submit for review.
          example: false
        missingRequirements:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationValidationIssue'
        invalidRequirements:
          type: array
          items:
            $ref: '#/components/schemas/PartnerIncorporationValidationIssue'
    PartnerIncorporationParticipantDocumentStatus:
      type: string
      description: Current status of the participant document link.
      enum:
        - SUBMITTED
    PartnerIncorporationValidationIssue:
      type: object
      required:
        - code
        - path
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable validation issue code.
          example: PARTICIPANT_DOCUMENT_REQUIRED
        path:
          type: string
          description: Dot/bracket path for the missing or invalid requirement.
          example: participants.participant_123.documents.PASSPORT_SCAN
        message:
          type: string
          example: Participant participant_123 requires a PASSPORT_SCAN document
        participantId:
          type: string
          description: Included when the issue belongs to a participant.
          example: participant_123
        documentKind:
          $ref: '#/components/schemas/PartnerIncorporationDocumentKind'
        displayName:
          type: string
          description: >-
            Included when available so UIs can render useful labels without
            joining across responses.
          example: Jane Founder
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````