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.

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

  Property	Description	Type
  id	The unique internal identifier of the attachment category.	integer($int64)
  displayName	The display name of the attachment category.	string

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

  Property	Description	Type
  id	The unique internal identifier of the booking type.	integer($int64)
  displayName	The display name of the booking type.	string

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

  Property	Description	Type
  id	The unique internal identifier of the expense item.	integer($int64)
  displayName	The display name of the expense item.	string

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

  Property	Description	Type
  id	The unique internal identifier of the booking type.	integer($int64)
  displayName	The display name of the booking type.	string

• 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

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

  Property	Description	Type
  id	The unique internal identifier of the assignment group.	integer($int64)
  displayName	The display name of the assignment group.	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	attachmentCategoryId	attachmentCategory	Returns the display name of the attachment category.
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.
Booking	attachments	attachment	Returns the metadata for all attachments associated with the booking.
Booking	bookingTypeID	bookingTypeDisplayName	Returns the display name of the booking type.
Booking	jobCodeID	jobCodeDisplayName	Returns the display name of the job code associated with the booking.
Booking	ownerId	userDisplayName	Returns the display name of the employee who created the booking.
Booking	userId	userDisplayName	Returns the display name of the employee associated with the booking — the resource booked.
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.
ProjectTask	assignedGroups	projectGroupDisplayName	Returns the name of the project assignment group.
Receipt	attachments	attachment	Returns the metadata for all attachments associated with the receipt.
Receipt	itemId	itemDisplayName	Returns the display name of the expense item associated with the receipt.
Receipt	userId	userDisplayName	Returns the display name of the employee associated with the receipt.
TimeEntry	jobCodeID	jobCodeDisplayName	Returns the display name of the job code associated with the time entry.
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.
User	jobCodeID	jobCodeDisplayName	Returns the display name of the job code associated with the user.