Working with user-defined dimensions

A dimension is a classification used to organize, sort, and report on company information. Dimension values can be set on transactions and then reports can be built that show amounts and totals by each dimension value.

Sage Intacct includes many standard dimensions such as location and department, and there are REST API objects for each one. Companies can also create user-defined dimensions (UDDs) to track and report on other factors that matter to their business. Note that UDDs can only be created in the UI, but you can use the REST API to create UDD records, and to list, query, get, update, and delete records for UDDs.

This guide outlines how to interact with user-defined dimensions using the Sage Intacct REST API.

UUDs in transactions

User-defined dimensions can be deployed to any object or transaction that supports dimensions. The UDD will be included in the dimensions object along with all standard dimensions that are in use by a company. The documentation and downloadable schema files don't include UDDs, but you can use the model service to get current definitions of objects as they are used in a company.

UDD object names and integration names

In the REST API, the object name of a user-defined dimension is comprised of the default namespace prefix nsp and the delimiter ::, followed by the UDD integration name. For example nsp::travel. You must include the nsp:: prefix when working with UDDs.

There are a few ways to find a UDD's integration name.

  • Using the REST API list dimension service to find the dimensionName . Note that the dimensionName is shown in all uppercase, but you must use the capitalization as it was set when the UDD was created.
  • Using the REST API model service and searching for nsp in the response. The search results will include custom objects and UDDs.
  • Navigating in the Sage Intacct UI to Reports > Setup, clicking on the name of the UDD, then clicking Object definition and noting the value in the Integration name field.

The id value for a UDD record is always the same as the key value. When issuing REST API requests for a specific UDD record, specify the key for the record you want to access.

All UDDs are in the /objects/platform-apps area of the API, so the endpoint URLs to access UDDs include this directory.

Find all UDDs

The list dimensions service returns all dimensions in use by a company, including user-defined dimensions. This abbreviated example response includes a UDD at the bottom.

Copy
Copied
{
    "ia::result": [
        {
            "dimensionName": "DEPARTMENT",
            "dimensionLabel": "Department",
            "termName": "Department",
            "isUserDefinedDimension": false,
            "isEnabledInGL": true,
            "dimensionEndpoint": "/objects/company-config/department"
        },
        {
            "dimensionName": "LOCATION",
            "dimensionLabel": "Location",
            "termName": "Location",
            "isUserDefinedDimension": false,
            "isEnabledInGL": true,
            "dimensionEndpoint": "/objects/company-config/location"
        },
        .
        .
        .
        {
            "dimensionName": "TRAVEL_UDD",
            "dimensionLabel": "Travel",
            "termName": "Travel",
            "isUserDefinedDimension": true,
            "isEnabledInGL": true,
            "dimensionEndpoint": "/objects/platform-apps/nsp::travel_UDD"
        }
    ],
    "ia::meta": {
        "totalCount": 16,
        "totalSuccess": 16,
        "totalError": 0
    }
}

Query UDDs

To retrieve UDD records that match specific values, use the query service. You must specify the nsp name of the UDD in the request body.

Endpoint

POST https://api.intacct.com/ia/api/{version}/services/core/query

Example request body

The following example request body shows how to query a user-defined dimension:

Copy
Copied
{
    "object": "platform-apps/nsp::travel_UDD",

    "fields": [
        "id,
        "key",
        "name",
        "href"
    ],
    "orderBy": [
        {"name": "asc"}
    ]
}

Example response

If you queried a UDD with an integration name of travel_UDD for the same fields listed in the preceding example request body, the response would include data like the following:

Copy
Copied
{
    "ia::result": [
        {
            "key": "10079",
            "id": "10079",
            "name": "Domestic",
            "href": "/objects/platform-apps/nsp::travel_UDD/10079"
        },
        {
            "key": "10080",
            "id": "10080",
            "name": "International",
            "href": "/objects/platform-apps/nsp::travel_UDD/10080"
        }
    ],
    "ia::meta": {
        "totalCount": 2,
        "start": 1,
        "pageSize": 100,
        "next": null,
        "previous": null
    }
}

List UDD records

To return a collection with a key, ID, and link for each record for a user-defined dimension, send a GET request to the object's integration name endpoint.

Endpoint

GET https://api.intacct.com/ia/api/{version}/objects/platform-apps/nsp::{integration_name}

Replace {integration_name} in the request endpoint with the integration name of your UDD.

Example response

If you issued a GET request for a user-defined dimension with an integration name of travel_UDD, a successful response would include data like the following:

Copy
Copied
{
    "ia::result": [
        {
            "key": "7",
            "id": "7",
            "href": "/objects/platform-apps/nsp::travel_UDD/7"
        },
        {
            "key": "8",
            "id": "8",
            "href": "/objects/platform-apps/nsp::travel_UDD/8"
        }
    ],
    "ia::meta": {
        "totalCount": 2,
        "start": 1,
        "pageSize": 100,
        "next": null,
        "previous": null
    }
}

Create a UDD record

To create a new UDD record, send a POST request with the required data in the request body.

Endpoint

POST https://api.intacct.com/ia/api/{version}/objects/platform-apps/nsp::{integration_name}

Replace {integration_name} in the request endpoint with the integration name of the UDD.

Example request body

Ensure all required fields are included in the request body. In this example, name is the only required field.

Copy
Copied
{
    "name": "Interplanetary"
}

Example response

If you added the preceding new record to a UDD with an integration name of travel_UDD, a successful response would include data like the following:

Copy
Copied
{
    "ia::result": {
        "key": "9",
        "id": "9",
        "href": "/objects/platform-apps/nsp::travel_UDD/9"
    },
    "ia::meta": {
        "totalCount": 1,
        "totalSuccess": 1,
        "totalError": 0
    }
}

Get a UDD record

To return detailed information for a specified UDD record, issue a GET request with the record's key.

Endpoint

GET https://api.intacct.com/ia/api/{version}/objects/platform-apps/nsp::{integration_name}/:key

  • Replace {integration_name} in the request endpoint with the integration name of your UDD.
  • Replace :key with the unique key for the record.

Example response

If you requested a UDD record with a key of 8 and an integration name of travel_UDD, a successful response would include data like the following:

Copy
Copied
{
    "ia::result": {
        "name": "Domestic",
        "audit": {
            "createdBy": "1",
            "createdDateTime": "2025-04-01T18:09:46Z",
            "modifiedBy": "1",
            "modifiedDateTime": "2025-05-05T18:19:06Z"
        },
        "key": "8",
        "id": "8",
        "file": "fileName=/tmp/phpQamrJ7\ncontentType=image/jpeg\norigFileName=daisy.jpeg\nfileSize=2374\n",
        "description": "In-country travel",
        "href": "/objects/platform-apps/nsp::travel_UDD/8"
    },
    "ia::meta": {
        "totalCount": 1,
        "totalSuccess": 1,
        "totalError": 0
    }
}

Update a UDD record

To update an existing UDD record, send a PATCH request with the record's key and the updated field values in the request body.

Endpoint

PATCH https://api.intacct.com/ia/api/{version}/objects/platform-apps/nsp::{integration_name}/:key

  • Replace {integration_name} in the request endpoint with the integration name of your UDD.
  • Replace :key with the unique key for the record.

Example request body

This example request body updates the name of the UDD record.

Copy
Copied
{
    "name": "Domestic travel"
}

Example response

If you revised an existing record with a key of 9 in a UDD with an integration name of travel_UDD, a successful response would include data like the following:

Copy
Copied
{
    "ia::result": {
        "key": "9",
        "id": "9",
        "href": "/objects/platform-apps/nsp::travel_UDD/9"
    },
    "ia::meta": {
        "totalCount": 1,
        "totalSuccess": 1,
        "totalError": 0
    }
}

Delete a UDD record

To delete a UDD record, send a DELETE request with the key for the record you want to delete.

Note: Deleting a UDD record is irreversible. Deleted records cannot be retrieved.

Endpoint

DELETE https://api.intacct.com/ia/api/{version}/objects/platform-apps/nsp::{integration_name}/:key

  • Replace {integration_name} in the request endpoint with the integration name of your UDD.
  • Replace :key with the unique key for the UDD record.

Response

When a UDD record is successfully deleted, the response is 204 No Content.