---
title: "Add-Form"
slug: "scripting-add-form"
updated: 2026-01-21T13:42:12Z
published: 2026-01-21T13:42:12Z
canonical: "help.agilityblue.com/scripting-add-form"
---

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

# Add-Form

## Summary

Creates a new form.

```powershell
Add-Form
    -Entry
```

Returns a [form](https://apidocs.agilityblue.com/#8c402f05-727c-4464-94d7-4ba56805c1e3) object.

## Parameters

| Parameter | Type | Required? | Notes |
| --- | --- | --- | --- |
| Entry | [Form](https://apidocs.agilityblue.com/#8c402f05-727c-4464-94d7-4ba56805c1e3) Object | Yes |  |

## Examples

### Create a new form

```powershell
$ErrorActionPreference = 'Stop'

# Create a form object with required fields
$form = @{
    Name       = "My Form"
    Category   = "General"
    FormTypeId = 1
    Sections   = @(
        @{
            Heading = "Section 1"
            Fields  = @(
                @{
                    DataTypeId  = 1
                    Label       = "My Basic Text Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 1
                },
                @{
                    DataTypeId  = 2
                    Label       = "My Rich Text Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 2
                },
                @{
                    DataTypeId  = 3
                    Label       = "My Whole Number Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 3
                },
                @{
                    DataTypeId  = 4
                    Label       = "My Decimal Number Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 4
                },
                @{
                    DataTypeId  = 5
                    Label       = "My Yes or No Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 5
                },
                @{
                    DataTypeId  = 6
                    Label       = "My Date and Time Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 6
                },
                @{
                    DataTypeId  = 7
                    Label       = "My Date Only Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 7
                },
                @{
                    DataTypeId  = 8
                    Label       = "My Single Choice Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 8
                    DefaultValue = "Choice 1`nChoice 2`nChoice 3"
                },
                @{
                    DataTypeId  = 9
                    Label       = "My Multiple Choice Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 9
                    DefaultValue = "Item A`nItem B`nItem C"
                },
                @{
                    DataTypeId  = 10
                    Label       = "My Contacts Reference Field"
                    IsRequired  = $false
                    IsVisible   = $true
                    Position    = 10
                    ReferenceObject = @{ ObjectId = 7 }
                }
            )
        }
    )
}

# Add-Form may report a serialization error. The form gets created, but the system chokes on
# returning the data back, so we need to work around that.
function Test-IsKnownODataNullSourceError {
    param([Parameter(Mandatory)] [object]$ErrorRecord)

    # Unwrap AggregateException if present
    $ex = $ErrorRecord.Exception

    if ($ex -is [System.AggregateException] -and $ex.InnerExceptions.Count -gt 0) {
        $ex = $ex.InnerExceptions[0]
    }

    # Walk inner exceptions and look for the specific serialization error message
    while ($null -ne $ex) {
        if ($ex.Message -match "Value cannot be null\.\s*\(Parameter 'source'\)") {
            return $true
        }

        $ex = $ex.InnerException
    }

    return $false
}

try { 
    Add-Form -Entry $form -ErrorAction Stop | Out-Null
}
catch {
    if (Test-IsKnownODataNullSourceError $_) {
        # Clear the error so it doesn't remain in $Error
        $global:Error.RemoveAt(0) 2>$null
    }
    else {
        throw
    }
}

# Verify the form exists
$formsResult = Get-Forms -Filter "Name eq 'My Form' and Category eq 'General'" -Top 1

$createdForm = $formsResult.Collection | Select-Object -First 1

if ($null -eq $createdForm) {
    Write-Error "Encountered an error while creating the form"
    exit 1
}

# Now fetch the fully-expanded form using `Get-Form`
$fullForm = Get-Form -Id $createdForm.FormId

Write-Output "Created form '$($fullForm.Name)' (#$($fullForm.FormId), # of sections: $($fullForm.NumberOfSections), # of fields: $($fullForm.NumberOfFields))"

Write-Output ""
Write-Output "JSON Results:"
Write-Output ($fullForm | ConvertTo-Json -Depth 10)
```

Execution results:

```json
Created form 'My Form' (#99, # of sections: 1, # of fields: 10)

JSON Results:
{
  "FormId": 99,
  "FormTypeId": 1,
  "FormType": null,
  "FormTypeName": "Tasks",
  "Name": "My Form",
  "Category": "General",
  "Description": null,
  "IsAvailableOnPortal": false,
  "NumberOfSections": 1,
  "NumberOfFields": 10,
  "CreatedByFullName": "Max Miller",
  "CreatedById": "510e109b-6ff5-4442-9670-cd5e3cd82a7a",
  "CreatedOn": "2026-01-21T13:07:18.6211605+00:00",
  "CreatedBy": null,
  "LastUpdatedByFullName": "Max Miller",
  "LastUpdatedById": "510e109b-6ff5-4442-9670-cd5e3cd82a7a",
  "LastUpdatedOn": "2026-01-21T13:07:18.6211605+00:00",
  "LastUpdatedBy": null,
  "Sections": [
    {
      "SectionId": 120,
      "FormId": 99,
      "Heading": "Section 1",
      "Position": 0,
      "Guid": 1148648158110,
      "Fields": [
        {
          "FieldId": 475,
          "SectionId": 120,
          "DataTypeId": 1,
          "DataTypeName": "Basic Text",
          "Label": "My Basic Text Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 1,
          "Guid": 4167049853533,
          "DefaultValue": null,
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 476,
          "SectionId": 120,
          "DataTypeId": 2,
          "DataTypeName": "Rich Text",
          "Label": "My Rich Text Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 2,
          "Guid": 6798658424189,
          "DefaultValue": null,
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 477,
          "SectionId": 120,
          "DataTypeId": 3,
          "DataTypeName": "Whole Number",
          "Label": "My Whole Number Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 3,
          "Guid": 5168576493377,
          "DefaultValue": null,
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 478,
          "SectionId": 120,
          "DataTypeId": 4,
          "DataTypeName": "Decimal Number",
          "Label": "My Decimal Number Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 4,
          "Guid": 9276055131768,
          "DefaultValue": null,
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 479,
          "SectionId": 120,
          "DataTypeId": 5,
          "DataTypeName": "Yes or No Choice",
          "Label": "My Yes or No Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 5,
          "Guid": 6772880977176,
          "DefaultValue": null,
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 480,
          "SectionId": 120,
          "DataTypeId": 6,
          "DataTypeName": "Date Only",
          "Label": "My Date and Time Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 6,
          "Guid": 287848767297,
          "DefaultValue": null,
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 481,
          "SectionId": 120,
          "DataTypeId": 7,
          "DataTypeName": "Date and Time",
          "Label": "My Date Only Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 7,
          "Guid": 7568294219059,
          "DefaultValue": null,
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 482,
          "SectionId": 120,
          "DataTypeId": 8,
          "DataTypeName": "Single Choice",
          "Label": "My Single Choice Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 8,
          "Guid": 5957387833874,
          "DefaultValue": "Choice 1\nChoice 2\nChoice 3",
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 483,
          "SectionId": 120,
          "DataTypeId": 9,
          "DataTypeName": "Multiple Choice",
          "Label": "My Multiple Choice Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 9,
          "Guid": 9747052228830,
          "DefaultValue": "Item A\nItem B\nItem C",
          "ReferenceObject": null,
          "ConditionGroups": [],
          "AppliedProperties": []
        },
        {
          "FieldId": 484,
          "SectionId": 120,
          "DataTypeId": 10,
          "DataTypeName": "Reference",
          "Label": "My Contacts Reference Field",
          "IsRequired": false,
          "IsVisible": true,
          "Position": 10,
          "Guid": 1617698717842,
          "DefaultValue": null,
          "ReferenceObject": {
            "FieldReferenceObjectId": 66,
            "FieldId": 484,
            "ObjectId": 7,
            "Object": null,
            "KeyType": "Int32",
            "DisplayFormat": "%Val%",
            "IsSystemObject": true,
            "Name": "Contact",
            "DefaultValues": []
          },
          "ConditionGroups": [],
          "AppliedProperties": []
        }
      ]
    }
  ]
}
```