StringValue

A wrapper type that encapsulates a string value in API requests and responses.

Overview

StringValue is used throughout the Acumatica API to wrap string properties. This wrapper pattern allows the API to distinguish between "no value provided" (field omitted) and "explicitly set to null or empty".

JSON Structure

{
  "value": "Sample text"
}

Examples

Reading a StringValue

When retrieving an entity, string properties are returned as objects:

{
  "CustomerID": {
    "value": "CUST001"
  },
  "Description": {
    "value": "Main customer account"
  }
}

Setting a StringValue

When creating or updating an entity, provide the value in the wrapper:

{
  "CustomerID": {
    "value": "NEWCUST"
  }
}

Clearing a StringValue

To clear a string field, set the value to null or empty:

{
  "Description": {
    "value": null
  }
}

Properties

Error Handling

All value wrapper types inherit an error property that contains a description when there is an issue with the field. This is critical for understanding validation failures or processing errors:

{
  "CustomerID": {
    "value": "INVALID",
    "error": "Customer 'INVALID' not found"
  }
}

Always check the error property when processing API responses to handle field-level issues appropriately.

Common Fields Using StringValue

• CustomerID, OrderNbr, Description
• Status, Type, Category
• Address fields, phone numbers, email addresses
• Any text or code field in the API