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

# Assign a form to clients

> Assigns a form to one or more clients, creating a pending form response for each recipient. Provide either clientIds or clientCompanyIds.


## OpenAPI

````yaml /api-reference/openapi.json post /v1/form-responses
openapi: 3.0.0
info:
  contact: {}
  title: Assembly API
  version: 0.0.1
servers:
  - url: https://api.assembly.com
security: []
paths:
  /v1/form-responses:
    post:
      tags:
        - Form Responses
      summary: Assign a form to clients
      description: >-
        Assigns a form to one or more clients, creating a pending form response
        for each recipient. Provide either clientIds or clientCompanyIds.
      operationId: request-form-response
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/forms.SendFormRequest'
        description: Form assignment request
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/forms.ListFormResponsesOutput'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispatcher.Error'
          description: Invalid request body or recipient information
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispatcher.Error'
          description: Missing or invalid API key
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispatcher.Error'
          description: Form not found or could not be assigned
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispatcher.Error'
          description: Unexpected server error
      security:
        - APIKeyHeader: []
components:
  schemas:
    forms.SendFormRequest:
      properties:
        clientCompanyIds:
          description: >-
            Client/company pairs to assign the form to. Required when clientIds
            is omitted.
          items:
            $ref: '#/components/schemas/forms.RecipientInfo'
          type: array
        clientIds:
          description: >-
            Client IDs to assign the form to. Required when clientCompanyIds is
            omitted.
          example:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          items:
            type: string
          type: array
        formId:
          description: ID of the form to assign.
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          format: uuid
          type: string
      required:
        - formId
      type: object
    forms.ListFormResponsesOutput:
      properties:
        data:
          description: The page of form responses.
          items:
            $ref: '#/components/schemas/forms.FormResponse'
          nullable: true
          type: array
        nextToken:
          description: base64 encoded JSON representing a NextToken
          type: string
      type: object
    dispatcher.Error:
      properties:
        code:
          type: string
        data: {}
        message:
          type: string
      type: object
    forms.RecipientInfo:
      properties:
        clientId:
          example: a1b2c3d4-5678-90ab-cdef-1234567890ab
          format: uuid
          type: string
        companyId:
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          format: uuid
          type: string
      type: object
    forms.FormResponse:
      properties:
        clientId:
          description: ID of the client the response is assigned to.
          example: a1b2c3d4-5678-90ab-cdef-1234567890ab
          format: uuid
          type: string
        companyId:
          description: ID of the company the client belongs to for this response.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          format: uuid
          type: string
        createdAt:
          type: string
        creatorId:
          type: string
        data:
          type: string
        fields:
          $ref: '#/components/schemas/forms.FormResponseFields'
        filteredListIndexPkey:
          type: string
        formId:
          description: ID of the form this response belongs to.
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
          format: uuid
          type: string
        id:
          type: string
        identityId:
          type: string
        object:
          type: string
        owner:
          $ref: '#/components/schemas/users.Owner'
        previousAttributes:
          additionalProperties: true
          type: object
        ref:
          type: string
        updatedAt:
          type: string
      type: object
    forms.FormResponseFields:
      properties:
        allowMultipleSubmissions:
          description: Whether the originating form allows multiple submissions.
          example: false
          type: boolean
        formDescription:
          description: Description of the form at the time the response was created.
          example: Tell us about your business so we can tailor onboarding.
          type: string
        formFieldIds:
          description: IDs of the form's questions, in display order.
          example:
            - q_abc123
            - q_def456
          items:
            type: string
          nullable: true
          type: array
        formFields:
          additionalProperties:
            $ref: '#/components/schemas/forms.FormResponseQuestion'
          description: Answered questions keyed by question ID.
          nullable: true
          type: object
        formName:
          description: Name of the form at the time the response was created.
          example: Client Intake Form
          type: string
        status:
          description: Completion status of the response.
          enum:
            - pending
            - completed
            - open
          example: pending
          type: string
        submissionDate:
          description: Timestamp the client completed the response, if completed.
          format: date-time
          type: string
        visibility:
          allOf:
            - $ref: '#/components/schemas/forms.FormVisibilityType'
          description: Visibility of the originating form.
          enum:
            - requestedClients
            - allClients
          example: requestedClients
      type: object
    users.Owner:
      properties:
        id:
          type: string
        metadata:
          $ref: '#/components/schemas/users.OwnerFields'
      type: object
    forms.FormResponseQuestion:
      properties:
        answer:
          description: >-
            Answer given by the client. Its shape depends on the question Type:
            a string for

            text/date/email questions, a string array for multiSelect, or file
            names for fileUpload.
          oneOf:
            - type: string
            - items:
                type: string
              type: array
        attachmentUrls:
          description: >-
            Presigned download URLs for fileUpload answers, valid for 15
            minutes.
          items:
            type: string
          type: array
        description:
          example: As it appears on your incorporation documents.
          type: string
        hasOtherOption:
          example: false
          type: boolean
        isRequired:
          example: true
          type: boolean
        multipleChoiceOptions:
          example:
            - Option A
            - Option B
          items:
            type: string
          type: array
        title:
          description: Values copied from question template
          example: What is your company name?
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/forms.FormFieldType'
          enum:
            - shortAnswer
            - longAnswer
            - singleSelect
            - multiSelect
            - title
            - fileUpload
            - phoneNumber
            - email
            - date
            - dropdown
          example: shortAnswer
      type: object
    forms.FormVisibilityType:
      enum:
        - requestedClients
        - allClients
      type: string
      x-enum-varnames:
        - FormVisibilityTypeOnSend
        - FormVisibilityTypeAllClients
    users.OwnerFields:
      properties:
        avatarImageUrl:
          type: string
        companyAvatarUrl:
          type: string
        companyId:
          type: string
        companyName:
          type: string
        email:
          type: string
        fallbackColor:
          type: string
        familyName:
          type: string
        givenName:
          type: string
      type: object
    forms.FormFieldType:
      enum:
        - shortAnswer
        - longAnswer
        - singleSelect
        - multiSelect
        - title
        - fileUpload
        - phoneNumber
        - email
        - date
        - dropdown
      type: string
      x-enum-varnames:
        - FormFieldTypeShortAnswer
        - FormFieldTypeLongAnswer
        - FormFieldTypeSingleSelect
        - FormFieldTypeMultiSelect
        - FormFieldTypeTitle
        - FormFieldTypeFileUpload
        - FormFieldTypePhoneNumber
        - FormFieldTypeEmail
        - FormFieldTypeDate
        - FormFieldTypeDropdown
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-KEY
      type: apiKey

````