---
title: "Add-Matter"
slug: "scripting-add-matter"
updated: 2026-01-22T13:32:49Z
published: 2026-01-22T13:32:49Z
canonical: "help.agilityblue.com/scripting-add-matter"
---

> ## 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-Matter

## Summary

Creates a new matter.

```powershell
Add-Matter
    -Entry
    -BypassCustomFieldValidation
```

Returns a [matter](https://apidocs.agilityblue.com/#788f3287-6ef8-446e-a192-05652d583944) object.

## Parameters

| Parameter | Type | Required? | Notes |
| --- | --- | --- | --- |
| Entry | [Matter](https://apidocs.agilityblue.com/#788f3287-6ef8-446e-a192-05652d583944) Object | Yes |  |
| BypassCustomFieldValidation | Switch | No, Defaults to false | Ignores required field requirement for custom fields when the entry is saved. |

## Examples

### Create a new matter (no custom fields)

```powershell
# Create a new matter (no custom fields)

# Create an object with the necessary fields to create the matter
# Note: The ClientId field is required. It needs to be the ClientId field found on 
#       the parent client.
# Note: The Reference field is not required, but we're including it here due to how
#       common it is to contain information.

$entry = @{
    ClientId    = 67
    Name        = "Steel City Construction v Brick Masters"
    Reference   = "SCBM001"
}

# Create the matter. The created entry will be returned back.
$data = Add-Matter -Entry $entry

# Output some information to help indicate that the client was created
Write-Output "Matter $($data.MatterId) ($($data.Name)) was created on client $($data.ClientId) ($($data.ClientName))"

# For debug purposes, convert the data to output as JSON so we can see all the fields
Write-Output ""
Write-Output "JSON Results:"

$jsonOutput = $data | ConvertTo-Json -Depth 10

# Output the data
Write-Output $jsonOutput
```

Execution results:

```json
Matter 99 (Steel City Construction v Brick Masters) was created on client 67 (QuantumTech v. CyberInnovate)

JSON Results:
{
  "MatterId": 99,
  "Name": "Steel City Construction v Brick Masters",
  "Reference": "SCBM001",
  "Active": true,
  "ClientId": 67,
  "Client": null,
  "ClientName": "QuantumTech v. CyberInnovate",
  "ClientReference": "QT00001",
  "DefaultContactId": null,
  "DefaultContact": null,
  "DefaultContactFullName": null,
  "IsFavorite": false,
  "NumberOfProjects": 0,
  "NumberOfTasks": 0,
  "NumberOfMediaLogEntries": 0,
  "NumberOfVolumes": 0,
  "NumberOfBillingEntries": 0,
  "NumberOfComments": 0,
  "FirstProjectCreatedOnDate": null,
  "LastProjectCreatedOnDate": null,
  "CreatedByFullName": "Max Miller",
  "CreatedById": "25a34a2f-e3d8-4690-88f5-6b399cf88c4c",
  "CreatedOn": "2024-04-17T12:49:33.9343641+00:00",
  "CreatedBy": null,
  "LastUpdatedByFullName": "Max Miller",
  "LastUpdatedById": "25a34a2f-e3d8-4690-88f5-6b399cf88c4c",
  "LastUpdatedOn": "2024-04-17T12:49:33.9343641+00:00",
  "LastUpdatedBy": null,
  "Fields": [
    {
      "FieldId": 19,
      "ObjectId": 2,
      "DataTypeId": 5,
      "DataTypeName": "Yes or No Choice",
      "Label": "ESI Protocol Attached",
      "IsRequired": false,
      "Position": 0,
      "Guid": 1492029172604,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": "false",
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    },
    {
      "FieldId": 28,
      "ObjectId": 2,
      "DataTypeId": 2,
      "DataTypeName": "Rich Text",
      "Label": "Notes & Misc that can't fit in a single line",
      "IsRequired": false,
      "Position": 1,
      "Guid": 1531229623985,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    },
    {
      "FieldId": 29,
      "ObjectId": 2,
      "DataTypeId": 2,
      "DataTypeName": "Rich Text",
      "Label": "ESI Protocol",
      "IsRequired": false,
      "Position": 2,
      "Guid": 1570803558740,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    },
    {
      "FieldId": 51,
      "ObjectId": 2,
      "DataTypeId": 8,
      "DataTypeName": "Single Choice",
      "Label": "Team Color",
      "IsRequired": false,
      "Position": 3,
      "Guid": 8895432013021,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": "Red\nGreen\nBlue",
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    },
    {
      "FieldId": 63,
      "ObjectId": 2,
      "DataTypeId": 10,
      "DataTypeName": "Reference",
      "Label": "Skills",
      "IsRequired": false,
      "Position": 4,
      "Guid": 3294117251654,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    },
    {
      "FieldId": 66,
      "ObjectId": 2,
      "DataTypeId": 4,
      "DataTypeName": "Decimal Number",
      "Label": "Total Billing Amount",
      "IsRequired": false,
      "Position": 5,
      "Guid": 6886580921259,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": "0",
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    },
    {
      "FieldId": 70,
      "ObjectId": 2,
      "DataTypeId": 1,
      "DataTypeName": "Basic Text",
      "Label": "Email Domains",
      "IsRequired": false,
      "Position": 6,
      "Guid": 6721810143004,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    },
    {
      "FieldId": 72,
      "ObjectId": 2,
      "DataTypeId": 1,
      "DataTypeName": "Basic Text",
      "Label": "Media Log Entry Prefix",
      "IsRequired": false,
      "Position": 7,
      "Guid": 7749781040934,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": null,
      "ReferenceObject": null
    }
  ]
}
```

### Create a new matter (with custom fields)

```powershell
# Create a new matter (with custom fields)

# Create an object with the necessary fields to create the matter
# Note: The ClientId field is required. It needs to be the ClientId field found on 
#       the parent client.
# Note: The Reference field is not required, but we're including it here due to how
#       common it is to contain information.

$entry = @{
    ClientId    = 67
    Name        = "Titan Contractors v Reliable Renovations"
    Reference   = "TCRR001"
    Fields    = @(
      @{
        FieldId = 19
        Label   = "ESI Protocol Attached"
        Value   = @{
          ValueAsBoolean = $false
        }
      }
      @{
        FieldId = 28
        Label   = "Notes & Misc that can't fit in a single line"
        Value   = @{
          ValueAsString = "<p>Matter opened up on 1/1/2024</p><p>Data collected on 2/1/2024</p>"
        }
      }
      @{
        FieldId = 29
        Label   = "ESI Protocol"
        Value   = @{}
      }
      @{
        FieldId = 29
        Label   = "Team Color"
        Value   = @{
          ValueAsString = "Blue"
        }
      }
      @{
        FieldId = 63
        Label   = "Skills"
        Value   = @{
          ReferenceObject = @{
            Values = @(
              @{
                KeyAsInteger = 1
                Value = "Document Review"
              }
              @{
                KeyAsInteger = 2
                Value = "Analytics"
              }
            )
          }
        }
      }
      @{
        FieldId = 66
        Label   = "Total Billing Amount"
        Value   = @{
          ValueAsDecimal = 0.00
        }
      }
      @{
        FieldId = 70
        Label   = "Email Domains"
        Value   = @{
          ValueAsString = "titancontractors.com"
        }
      }
      @{
        FieldId = 29
        Label   = "Media Log Entry Prefix"
        Value   = @{
          ValueAsString = "TC"
        }
      }
    )
}

# Create the matter. The created entry will be returned back.
$data = Add-Matter -Entry $entry

# Output some information to help indicate that the client was created
Write-Output "Matter $($data.MatterId) ($($data.Name)) was created on client $($data.ClientId) ($($data.ClientName))"

# For debug purposes, convert the data to output as JSON so we can see all the fields
Write-Output ""
Write-Output "JSON Results:"

$jsonOutput = $data | ConvertTo-Json -Depth 10

# Output the data
Write-Output $jsonOutput
```

Execution results:

```json
Matter 100 (Titan Contractors v Reliable Renovations) was created on client 67 (QuantumTech v. CyberInnovate)

JSON Results:
{
  "MatterId": 100,
  "Name": "Titan Contractors v Reliable Renovations",
  "Reference": "TCRR001",
  "Active": true,
  "ClientId": 67,
  "Client": null,
  "ClientName": "QuantumTech v. CyberInnovate",
  "ClientReference": "QT00001",
  "DefaultContactId": null,
  "DefaultContact": null,
  "DefaultContactFullName": null,
  "IsFavorite": false,
  "NumberOfProjects": 0,
  "NumberOfTasks": 0,
  "NumberOfMediaLogEntries": 0,
  "NumberOfVolumes": 0,
  "NumberOfBillingEntries": 0,
  "NumberOfComments": 0,
  "FirstProjectCreatedOnDate": null,
  "LastProjectCreatedOnDate": null,
  "CreatedByFullName": "Max Miller",
  "CreatedById": "25a34a2f-e3d8-4690-88f5-6b399cf88c4c",
  "CreatedOn": "2024-04-17T13:08:50.8592386+00:00",
  "CreatedBy": null,
  "LastUpdatedByFullName": "Max Miller",
  "LastUpdatedById": "25a34a2f-e3d8-4690-88f5-6b399cf88c4c",
  "LastUpdatedOn": "2024-04-17T13:08:50.8592386+00:00",
  "LastUpdatedBy": null,
  "Fields": [
    {
      "FieldId": 19,
      "ObjectId": 2,
      "DataTypeId": 5,
      "DataTypeName": "Yes or No Choice",
      "Label": "ESI Protocol Attached",
      "IsRequired": false,
      "Position": 0,
      "Guid": 1492029172604,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": "false",
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2170,
        "ObjectFieldId": 19,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": null,
        "ValueAsBoolean": false,
        "ValueAsNumber": null,
        "ValueAsDecimal": null,
        "ValueAsDate": null,
        "ReferenceObject": null
      },
      "ReferenceObject": null
    },
    {
      "FieldId": 28,
      "ObjectId": 2,
      "DataTypeId": 2,
      "DataTypeName": "Rich Text",
      "Label": "Notes & Misc that can't fit in a single line",
      "IsRequired": false,
      "Position": 1,
      "Guid": 1531229623985,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2171,
        "ObjectFieldId": 28,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": "<p>Matter opened up on 1/1/2024</p><p>Data collected on 2/1/2024</p>",
        "ValueAsBoolean": null,
        "ValueAsNumber": null,
        "ValueAsDecimal": null,
        "ValueAsDate": null,
        "ReferenceObject": null
      },
      "ReferenceObject": null
    },
    {
      "FieldId": 29,
      "ObjectId": 2,
      "DataTypeId": 2,
      "DataTypeName": "Rich Text",
      "Label": "ESI Protocol",
      "IsRequired": false,
      "Position": 2,
      "Guid": 1570803558740,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2172,
        "ObjectFieldId": 29,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": null,
        "ValueAsBoolean": null,
        "ValueAsNumber": null,
        "ValueAsDecimal": null,
        "ValueAsDate": null,
        "ReferenceObject": null
      },
      "ReferenceObject": null
    },
    {
      "FieldId": 51,
      "ObjectId": 2,
      "DataTypeId": 8,
      "DataTypeName": "Single Choice",
      "Label": "Team Color",
      "IsRequired": false,
      "Position": 3,
      "Guid": 8895432013021,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": "Red\nGreen\nBlue",
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2173,
        "ObjectFieldId": 51,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": null,
        "ValueAsBoolean": null,
        "ValueAsNumber": null,
        "ValueAsDecimal": null,
        "ValueAsDate": null,
        "ReferenceObject": null
      },
      "ReferenceObject": null
    },
    {
      "FieldId": 63,
      "ObjectId": 2,
      "DataTypeId": 10,
      "DataTypeName": "Reference",
      "Label": "Skills",
      "IsRequired": false,
      "Position": 4,
      "Guid": 3294117251654,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2174,
        "ObjectFieldId": 63,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": null,
        "ValueAsBoolean": null,
        "ValueAsNumber": null,
        "ValueAsDecimal": null,
        "ValueAsDate": null,
        "ReferenceObject": {
          "ObjectFieldReferenceObjectInstanceId": 325,
          "ObjectFieldValueId": 2174,
          "ObjectId": 16,
          "Object": null,
          "PrimaryObjectId": 2,
          "PrimaryKeyId": 100,
          "KeyType": "Int32",
          "DisplayFormat": "%Name%",
          "IsSystemObject": false,
          "Name": null,
          "NumberOfValues": 2,
          "Values": [
            {
              "ObjectFieldReferenceObjectInstanceValueId": 240,
              "ObjectFieldReferenceObjectInstanceId": 325,
              "KeyAsString": null,
              "KeyAsInteger": 1,
              "KeyAsLong": null,
              "Value": "Document Review"
            },
            {
              "ObjectFieldReferenceObjectInstanceValueId": 241,
              "ObjectFieldReferenceObjectInstanceId": 325,
              "KeyAsString": null,
              "KeyAsInteger": 2,
              "KeyAsLong": null,
              "Value": "Analytics"
            }
          ]
        }
      },
      "ReferenceObject": null
    },
    {
      "FieldId": 66,
      "ObjectId": 2,
      "DataTypeId": 4,
      "DataTypeName": "Decimal Number",
      "Label": "Total Billing Amount",
      "IsRequired": false,
      "Position": 5,
      "Guid": 6886580921259,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": "0",
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2175,
        "ObjectFieldId": 66,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": null,
        "ValueAsBoolean": null,
        "ValueAsNumber": null,
        "ValueAsDecimal": 0.0000,
        "ValueAsDate": null,
        "ReferenceObject": null
      },
      "ReferenceObject": null
    },
    {
      "FieldId": 70,
      "ObjectId": 2,
      "DataTypeId": 1,
      "DataTypeName": "Basic Text",
      "Label": "Email Domains",
      "IsRequired": false,
      "Position": 6,
      "Guid": 6721810143004,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2176,
        "ObjectFieldId": 70,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": "titancontractors.com",
        "ValueAsBoolean": null,
        "ValueAsNumber": null,
        "ValueAsDecimal": null,
        "ValueAsDate": null,
        "ReferenceObject": null
      },
      "ReferenceObject": null
    },
    {
      "FieldId": 72,
      "ObjectId": 2,
      "DataTypeId": 1,
      "DataTypeName": "Basic Text",
      "Label": "Media Log Entry Prefix",
      "IsRequired": false,
      "Position": 7,
      "Guid": 7749781040934,
      "IsSystemField": false,
      "IsReferenceValue": false,
      "DefaultValue": null,
      "CopyPreviousValueOnSaveAndNew": false,
      "Value": {
        "ObjectFieldValueId": 2177,
        "ObjectFieldId": 72,
        "ObjectId": 2,
        "PrimaryKeyId": 100,
        "ValueAsString": null,
        "ValueAsBoolean": null,
        "ValueAsNumber": null,
        "ValueAsDecimal": null,
        "ValueAsDate": null,
        "ReferenceObject": null
      },
      "ReferenceObject": null
    }
  ]
}
```