1. API
  2. REST API
  3. Referenced Objects and Expansion

Referenced Objects and Expansion

You can expand objects referenced by internal ID in the main response elements (data array), if the referenced object type supports expansion. It can be used to return additional data in the same response without the need for separate requests. Some of this additional data is only available when using expansion.

If there are any attributes available for expansion in the main response elements (data array), the response automatically includes a relationships property in the response metadata (meta object) with information about the attributes available for expansion and the referenced objects (object type and internal ID).

To include the expanded objects in your response, use the expand query parameter. The JSON-encoded object returned will include the included property, an array of expanded objects.

For information about available expansions and supported object types, see Available Expansions and Supported Object Types.

Parameters

Parameter

Description

expand

A comma-separated list of attributes available for expansion. The comma-separated list may include spaces (or %20 in the URL encoded string).

Note:

Review the following:

  • If you use the expand parameter with a POST or PUT request and return_object is set to any value other than 0 (zero), the expand value must contain only attributes referencing a supported object type. If the comma-separated list includes at least one attribute that is not available for expansion, the request fails — an error is returned and the object is not added or updated. For more information about attributes available for expansion and supported object types, see Available Expansions and Supported Object Types.

Response

An expanded response includes the meta and included properties in the JSON-encoded object returned.

Note:

The main response element (data array) must include resource objects with attributes available for expansions for the following properties to be returned. Referenced objects metadata and expanded objects can be included in responses to GET request used to retrieve a list of objects or a single object, or in responses to PUT and POST requests if the return_object query parameter is set to any value other than 0 (zero).

Property

Description

meta

The response metadata object includes a relationships property — an array of objects containing information about attributes available for expansion in the main response elements (data array), and about referenced objects.

The relationships array is always included if there are any attributes available for expansion in the main response elements (data array).

Each object in the relationships array includes a key-value pair for each attribute available for expansion, where the key is the attribute available for expansion, and the value is an object with the following properties:

  • data — An object with the following attributes:

    • type — The referenced object type.

    • id — The internal ID of the referenced object is returned even If the object is referenced by a metavalue (negative integer) instead of an internal ID in the main response element (data array). The response substitutes the internal ID of the object for the metavalue reference. For information about possible metavalue references, see object property descriptions in REST API Endpoint Reference.

The key-value pair is omitted if there are no referenced objects (if the internal ID of the referenced object is 0).

The response metadata object also includes a warning property if the number expandable objects referenced in the main response elements is over the maximum number of expanded objects that can be returned by a single REST API request. For example: “Could not return all expanded objects. The response contains only the first 1,000 expanded objects. Use the limit parameter to reduce the number of main response objects and expanded objects returned.”.

included

An array of expanded objects. The objects in the included array have the following attributes:

  • type — The expanded object type.

  • data — The expanded object.

Each expanded object in the included array is unique. If the object is referenced multiple times in the main response elements (data array), the expanded object is only included one time in the included array.

The number of expanded objects that can be returned in the included array is limited to 1,000 objects by default. If the number of expandable objects referenced in the main response elements (data array) exceeds 1,000 objects that can be returned by a single request, the included array contains only the first 1,000 expanded objects. The response also includes a warning message in the meta object. To avoid this situation, use the limit parameter to reduce the number of main response objects and expanded objects returned. For more information about the limit parameter, see Pagination.

Note:

To review your requirements, and increase the maximum number of expanded objects that can be returned by a single REST API request, contact SuiteProjects Pro Support. Note that there will be a performance trade off if the maximum number of expanded object is increased.

Example

The following request returns the list of attachments associated with the receipt with the internal ID 467 with expansions for the lockedBy, uploadedBy and workspaceId attributes.

            GET /rest/v1/receipts/467/attachments?expand=lockedBy,uploadedBy,workspaceId

The response includes the following properties:

  • meta — the response metadata includes relationships information about the attributes available for expansion (uploadedBy and workspaceId) and the referenced object internal IDs and types (userDisplayName and workspace, respectively). The lockedBy attribute is omitted as the referenced object internal ID is 0 for all the main response elements in the data array (no referenced objects).

  • included — an array of expanded userDisplayName and workspace objects.

            {
    "included": [
        {
            "data": {
                "id": 12,
                "displayName": "Marc Collins"
            },
            "type": "userDisplayName"
        },
        {
            "data": {
                "created": "2020-12-10 08:09:21",
                "name": "Altima Technology",
                "updated": "2020-12-10 08:09:21",
                "id": 103
            },
            "type": "workspace"
        }
    "data" : [
        {
            "workspaceId": 103
            "isFolder": false,
            "fileName": "receipt1.jpg",
            "name": "receipt1.jpg",
            "isLocked": false,
            "uploadedBy": 12,
            "lockedBy": 0,
            "isExcludedFromAlert": false,
            "size": 17762,
            "attachmentCategoryId": 0,
            "created": "2020-12-13 07:01:00",
            "notes": "",
            "updated": "2020-12-13 07:01:00",
            "id": 1056,
            "fileType": "JPEG image data, JFIF standard 1.00, comment: \"LEAD Technologies Inc. V1.01\""
        }
    ],
    "message" : "success",
    "meta": {
       "relationships": [
                  {
                  "uploadedBy": {
                      "data": { "type": "userDisplayName", "id": 12 }
                  },
                  "workspaceId": {
                      "data": { "type": "workspace", "id": 103 }
                  }
             },
          ],
       "rowsPerPage": 100,
       "totalPages": 1,
       "totalRows": 1,
       "links": [
            {
                "rel": "self",
                "href": "https://company-id.app.netsuitesuiteprojectspro.com/rest/v1/receipts/467/attachments?expand=lockedBy,workspaceId,uploadedBy"
            }
       ]
    }
}

Available Expansions and Supported Object Types

The following object types support expansion:

  • attachment — See Attachment object properties.

  • projectStageName — The projectStageName object type is available only as an expanded object and has the following attributes:

    Property

    Description

    Type

    id

    The unique internal identifier of the project stage.

    integer($int64)

    name

    The name of the project stage.

    string

  • userDisplayName — The userDisplayName object type is available only as an expanded object and has the following attributes:

    Property

    Description

    Type

    id

    The unique internal identifier of the user.

    integer($int64)

    displayName

    The display name of the user.

    string

  • workspace — The workspace object type is available only as an expanded object and has the following attributes:

    Property

    Description

    Type

    created

    The date the workspace was created.

    string($date-time)

    id

    The unique internal identifier of the workspace.

    integer($int64)

    name

    The name of the workspace.

    string

    updated

    The date the workspace was last updated or modified.

    string($date-time)

The following table lists the main response attributes available for expansion:

Main response object

Attribute

Referenced object type

Description

Attachment

lockedBy

userDisplayName

Returns the display name of the employee who locked the attachment for editing.

Attachment

uploadedBy

userDisplayName

Returns the display name of the employee who uploaded the attachment file.

Attachment

workspaceId

workspace

Returns the workspace the attachment is associated with, if the attachment is a workspace document.

Customer

invoiceApprover, userId

userDisplayName

Returns the display name of the employee.

ExpenseReport

attachments

attachment

Returns the metadata for all attachments associated with the expense report.

ExpenseReport

userId

userDisplayName

Returns the display name of the employee associated with the expense report.

Project

attachments

attachment

Returns the metadata for all attachments associated with the project.

Project

bookingApprover, bookingRequestApprover, budgetApprover, expenseAllowanceApprover, expenseApprover, expenseAuthorizationApprover, invoiceApprover, projectApprover1, projectApprover2, projectApprover3, purchaseOrderApprover, purchaseRequestApprover, revenueApprover , timesheetApprover , userId

userDisplayName

Returns the display name of the employee.

Project

projectStageId

projectStageName

Returns the name of the project stage.

ProjectMilestones, ProjectPhase, ProjectTask

attachments

attachment

Returns the metadata for all attachments associated with the project milestone, phase, or task.

Receipt

attachments

attachment

Returns the metadata for all attachments associated with the receipt.

Receipt

userId

userDisplayName

Returns the display name of the employee associated with the receipt.

TimeEntry

userId

userDisplayName

Returns the display name of the employee associated with the time entry.

User

attachments

attachment

Returns the metadata for the attachment associated with the user.

User

bookingApprover, bookingRequestApprover, budgetApprover, dealBookingRequestApprover, expenseAllowanceApprover, expenseApprover, expenseAuthorizationApprover, lineManagerId, proposalApprover, purchaseOrderApprover, purchaseRequestApprover, resourceProfileApprover, scheduleRequestApprover, timesheetApprover

userDisplayName

Returns the display name of the employee.