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

# Start Installation

> This endpoint will create an installation record and return the information required to create a form for your user to fill out.



## OpenAPI

````yaml post /headless/startInstallation
openapi: 3.0.1
info:
  title: Embedded 2025-09
  version: '5.0'
servers:
  - url: https://production.runalloy.com
security: []
paths:
  /headless/startInstallation:
    post:
      summary: Start Installation
      description: >-
        This endpoint will create an installation record and return the
        information required to create a form for your user to fill out.
      operationId: start-installation
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            default: bearer YOUR_API_KEY
        - $ref: '#/components/parameters/xApiVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - userId
                - integrationId
              properties:
                userId:
                  type: string
                  description: ID of the user that will install your integration
                integrationId:
                  type: string
                  description: ID of the integration which is being installed
                credentialIds:
                  type: array
                  description: >-
                    List of credentials to be used in this installation. If the
                    user has authorized any of the apps in the integration more
                    than once, then this field is required. Otherwise, the
                    user's credentials will be automatically detected.
                  items:
                    type: string
                workflowIds:
                  type: array
                  description: >-
                    A list of workflows to include in this installation, if only
                    a subset is desired. If every workflow in the integration
                    will be installed, this field is optional.
                  items:
                    type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    data:
                      - workflowId: 65b7005ae9761102a64ddd3b
                        app: netsuite
                        blockId: 3a8a8e50-f0e5-488b-9b7b-53656e93d392
                        fields:
                          - name: customerEmail
                            displayName: Customer's Email
                            type: string
                            required: true
                    installationId: 65b701c2f5ba66db3bc53a68
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        workflowId:
                          type: string
                          example: 65b7005ae9761102a64ddd3b
                        app:
                          type: string
                          example: netsuite
                        blockId:
                          type: string
                          example: 3a8a8e50-f0e5-488b-9b7b-53656e93d392
                        fields:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                example: customerEmail
                              displayName:
                                type: string
                                example: Customer's Email
                              type:
                                type: string
                                example: string
                              required:
                                type: boolean
                                example: true
                                default: true
                  installationId:
                    type: string
                    example: 65b701c2f5ba66db3bc53a68
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: >-
                    {"message":"User is not authorized to install integrations
                    for this account"}
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      User is not authorized to install integrations for this
                      account
      deprecated: false
components:
  parameters:
    xApiVersion:
      name: x-api-version
      in: header
      required: true
      description: The version of the API to use. The current API version is **2025-09**.
      schema:
        type: string
        default: 2025-09

````