Working with custom objects

Custom objects in Sage Intacct allow developers to extend the platform with application-specific data structures. Use Platform Services in the Sage Intacct UI to create custom objects as described in Build your application with custom objects.

The REST API provides methods to query, get, create, update, and delete records for custom objects.

In the REST API, the name of a custom object is prepended with the default namespace nsp and the delimiter ::, for example nsp::unbilled or nsp::cip_asset. You must include the nsp:: prefix when working with custom objects.

All custom objects reside in /objects/platform-apps and so the endpoint URLs to access custom objects include this directory.

To issue API requests to a custom object, use its integration name, prefixed with nsp::. You can find a custom object's integration name by:

Using the REST API model service or
Navigating in the Sage Intacct UI to Platform Services > Objects, searching for your object, and noting the value in the Integration name field.

The key and id values for a custom object are always the same. When issuing REST API requests for a specific custom object, specify the key for the object you want to access.

This guide outlines how to interact with custom objects using the Sage Intacct REST API.

Query custom objects

To retrieve data from a custom object, use the query service. The query request should specify the object name, list of fields to include in the response, and pagination parameters. For details about the query service, see Query an object.

A custom object must include one or more records for the query response to return data for those records.

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 custom object. To understand and use the example:

Replace {integration_name} with the actual integration name of your custom object, prefixed with nsp:: .
The size parameter defines the number of records per response (max: 4000).
The start parameter determines the starting index for pagination.

Copy

Copied

{

"object": "platform-apps/nsp::{integration_name}",

"fields": [
  "id,
  "key",
  "name"
],

"size": 4000,
"start": 1

}

Example response

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

Copy

Copied

{
    "ia::result": [
        {
            "id": "11107",
            "key": "11107",
            "name": "Unbilled RefA"
        },
        {
            "id": "11108",
            "key": "11108",
            "name": "Unbilled RefB"
        },
        {
            "id": "11109",
            "key": "11109",
            "name": "Unbilled RefC"
        }
    ],
    "ia::meta": {
        "totalCount": 3,
        "start": 1,
        "pageSize": 4000,
        "next": null,
        "previous": null
    }
}

List custom objects

To return a collection with a key, ID, and link for each custom object, send a GET request.

Endpoint

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

Replace {integration_name} in the request endpoint with the actual integration name of your custom object, prefixed with nsp::.

Example response

If you issued a GET request for a custom object with an integration name of unbilled, a successful response would include data like the following:

Copy

Copied

{
    "ia::result": [
        {
            "key": "11107",
            "id": "11107",
            "href": "/objects/platform-apps/nsp::unbilled/11107"
        },
        {
            "key": "11108",
            "id": "11108",
            "href": "/objects/platform-apps/nsp::unbilled/11108"
        },
        {
            "key": "11109",
            "id": "11109",
            "href": "/objects/platform-apps/nsp::unbilled/11109"
        }
    ],
    "ia::meta": {
        "totalCount": 3,
        "start": 1,
        "pageSize": 100,
        "next": null,
        "previous": null
    }
}

Create a custom object

To create a new custom object, 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 actual integration name of your custom object, prefixed with nsp::.

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": "Unbilled Ref D"

}

Example response

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

Copy

Copied

{
    "ia::result": {
        "key": "12090",
        "id": "12090",
        "href": "/objects/platform-apps/nsp::unbilled/12090"
    },
    "ia::meta": {
        "totalCount": 1,
        "totalSuccess": 1,
        "totalError": 0
    }
}

Get a custom object

To return detailed information for a specified custom object, issue a GET request with the custom object'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 actual integration name of your custom object, prefixed with nsp:: .
Replace :key with the unique key for the object, which you can obtain by listing custom objects as shown in List custom objects .

Example response

If you requested a custom object with a key of 11108 and an integration name of unbilled, a successful response would include data like the following:

Copy

Copied

{
    "ia::result": {
        "name": "Unbilled",
        "audit": {
            "createdBy": "65",
            "createdDateTime": "2024-03-27T17:03:55Z",
            "modifiedBy": "65",
            "modifiedDateTime": "2024-03-27T17:04:06Z"
        },
        "key": "11108",
        "id": "11108",
        "RTIMESHEETENTRY": "340",
        "object_action": "create",
        "timesheet_entry_key": "340",
        "journal_entry_key": "3538",
        "incoming_date": "09/26/2022",
        "ui_update": false,
        "href": "/objects/platform-apps/nsp::unbilled/11108"
    },
    "ia::meta": {
        "totalCount": 1,
        "totalSuccess": 1,
        "totalError": 0
    }
}

Update a custom object

To update an existing custom object, send a PATCH request with the object'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 actual integration name of your custom object, prefixed with nsp:: .
Replace :key with the unique key for the object, which you can obtain by listing custom objects as shown in List custom objects .

Example request body

This example request body updates the name of the custom object.

Copy

Copied

{

"name": "Unbilled Ref Department"

}

Example response

If you revised an existing record with a key of 12090 in a custom object with an integration name of unbilled, a successful response would include data like the following:

Copy

Copied

{
    "ia::result": {
        "key": "12090",
        "id": "12090",
        "href": "/objects/platform-apps/nsp::unbilled/12090"
    },
    "ia::meta": {
        "totalCount": 1,
        "totalSuccess": 1,
        "totalError": 0
    }
}

Delete a custom object

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

Note: Deleting a custom object 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 actual integration name of your custom object, prefixed with nsp:: .
Replace :key with the unique key for the custom object, which you can obtain by listing custom objects as shown in List custom objects .

Response

When a custom object is successfully deleted, the response is 204 No Content. A successful DELETE request always returns 204, indicating that the custom object longer exists.