Using Custom Object APIs

Liferay 7.4+

When you publish a custom object definition, Liferay generates default REST APIs for interacting with the object and its data. These APIs vary depending on the object’s scope (i.e., company or site). If the definition includes relationships or standalone actions, Liferay also generates endpoints for calling them.

The path for these headless services follows the c/[pluralobjectlabel] naming pattern (e.g., /o/c/timeoffrequests). You can view and test available object APIs via the Liferay API Explorer at [server]:[port]/o/api (e.g., localhost:8080/o/api). Click REST Applications to see a drop-down list of APIs.

While the object is active, you can use these APIs to perform basic CRUD operations, run complex queries using aggregation terms and nested fields, trigger standalone actions, manage entry relationships, and more.

Default Company-Scoped REST APIs

Default REST APIs are available for all company-scoped objects.

HTTP Method	HTTP Endpoint	Description
DELETE	/by-external-reference-code/{erc}	Deletes the specified entry and returns a 204 if the operation succeeds
GET	/by-external-reference-code/{erc}	Returns details for the specified entry
PATCH	/by-external-reference-code/{erc}	Updates the specified entry; only fields included in the API call are changed
PUT	/by-external-reference-code/{erc}	Replaces the specified entry’s details with those provided in the API call
GET	/	Returns a complete list of entries in a Liferay instance; you can paginate, filter, search, and sort results
POST	/	Creates a new entry using the details provided in the API call
DELETE	/batch	Deletes multiple entries and returns a 204 if the operation succeeds
POST	/batch	Creates multiple entries using the details provided in the API call
PUT	/batch	Replaces multiple entries using the details provided in the API call
DELETE	/{entryId}	Deletes the specified entry and returns a 204 if the operation succeeds
GET	/{entryId}	Returns details for the specified entry
PATCH	/{entryId}	Updates the specified entry; only fields included in the API call are changed
PUT	/{entryId}	Replaces the specified entry’s details with those provided in the API call

Note

Batch operations are only available for company-scoped objects.

Default Site-Scoped REST APIs

Default REST APIs are available for all site-scoped objects.

HTTP Method	HTTP Endpoint	Description
DELETE	/scopes/{scopeKey}/by-external-reference-code/{erc}	Deletes the specified entry and returns a 204 if the operation succeeds
GET	/scopes/{scopeKey}/by-external-reference-code/{erc}	Returns details for the specified entry
PATCH	/scopes/{scopeKey}/by-external-reference-code/{erc}	Updates the specified entry; only fields included in the API call are changed
PUT	/scopes/{scopeKey}/by-external-reference-code/{erc}	Replaces the specified entry’s details with those provided in the API call
GET	/scopes/{scopeKey}	Returns a complete list of entries in the specified scope; you can paginate, filter, search, and sort results
POST	/scopes/{scopeKey}	Creates a new entry in the specified scope using the details provided in the API call
DELETE	/{entryId}	Deletes the specified entry and returns a 204 if the operation succeeds
GET	/{entryId}	Returns details for the specified entry
PATCH	/{entryId}	Updates the specified entry; only fields included in the API call are changed
PUT	/{entryId}	Replaces the specified entry’s details with those provided in the API call

Note

For the scopeKey, use the proper identifier for the desired data scope (e.g., site ID or user role).

Relationship REST APIs

Liferay 7.4 U70+/GA70+

When you define one-to-many and many-to-many relationships between objects, Liferay generates endpoints for querying and managing entry relationships. This includes a GET endpoint for returning related object entries, PUT endpoints for relating entries, and a DELETE endpoint for disassociating related entries. See Using Relationship APIs for more information.

For the HTTP endpoints, replace relationshipName with the name of your relationship (e.g., userToTicket).

HTTP Method	HTTP Endpoint	Description
GET	/{entryId}/relationshipName	Returns all entries related to the specified entry through the relationship
PUT	/{entryId}/relationshipName/{relatedEntryId}	Uses the relationship to relate the specified object entries
PUT	/by-external-reference-code/{erc}/relationshipName/{relatedERC}	Uses the relationship to relate the specified object entries
DELETE	/{entryId}/relationshipName/{relatedEntryId}	Disassociates the specified object entries

For site-scoped objects, the ERC endpoint includes the /scope/{scopeKey} prefix (e.g., /scope/{scopeKey}/by-external-reference-code/{erc}/relationshipName/{relatedERC}). External reference code endpoints are not available for system objects.

Using nestedFields to Query Relationships

In addition to the dedicated relationship APIs, you can use the nestedFields query parameter with the object’s other GET APIs to return an entry with its related entries.

When using this parameter, you must provide the name of the relationship you want to include in the output (e.g., nestedFields=ticketAssignee), like this example:

curl \
     "http://localhost:8080/o/c/ables/by-external-reference-code/${1}?nestedFields=charlieToAble" \
     --user "[e-mail]:learn"

You can also use a nestedFields field in your object JSON (using the relationship name as the field name) for POST, PUT, or PATCH endpoints to define new relationships for the object.

For example, this POST command creates a new university object with a one-to-many relationship (called rUniversityStudents) to a student with ID 1234:

{
  "name": "New University",
  "universityStudents": [
    {
      "name": "Carlos",
      "id": "12345"
    }
  ]
}

See Using nestedFields to Query Related Entries for more information and an introductory tutorial to nestedFields.

Identifying a Related Object in the Query

Liferay DXP 2025.Q1+/Portal GA132+

Note

Before Liferay DXP 2025.Q1/Portal GA132, you must include all identifiers (including any mandatory relationships) for the related object to use these endpoints.

When you call a parent object’s PUT, POST, or PATCH APIs to define a new mandatory relationship between two objects, you can specify the child object to relate to with any of these identifiers, respected with this priority:

1. A nestedFields JSON object specifying the related object’s ID ("id").

2. A nestedFields JSON object specifying the related object’s external reference code ("externalReferenceCode").

3. The related object’s ID.

4. The related object’s external reference code (ERC).

If you define multiple identifiers, only the highest-priority identifier is used when creating the relationship. For example, if you specify an ID and an external reference code, only the ID is used, and the external reference code is ignored.

Standalone Action REST APIs

Liferay 7.4 U60+/GA60+

When you define standalone actions for a published object, Liferay generates two endpoints for triggering the action on an entry. One uses the entry’s ID and the other uses the entry’s external reference code (ERC). See Using Manual Actions for more information.

HTTP Method	HTTP Endpoint
PUT	/by-external-reference-code/{erc}/object-actions/actionName
PUT	/{entryId}/object-actions/actionName

For site-scoped objects, the ERC endpoint includes the /scope/{scopeKey} prefix (e.g., /scopes/{scopeKey}/by-external-reference-code/{erc}/object-actions/actionName).

GraphQL APIs

With the GraphQL APIs, you can both query and mutate object data. All APIs for custom objects are listed under c in Liferay’s GraphQL schema. You can use Liferay’s integrated GraphiQL IDE to search object schemas, draft queries, run requests, and more. To access it, go to Liferay’s API Explorer at [server]:[port]/o/api (e.g., localhost:8080/o/api) and click GraphQL.

See Consuming GraphQL APIs for more information.

Exporting and Importing Objects

You can export and import objects data using the Data Migration Center or the batch framework’s export and import endpoints.

Attachment fields store their files in the document library. Beginning in Liferay DXP 2024.Q4, the link between attachments and object entries is made with the ERC so the link is preserved on export/import. Exporting and importing objects with attachments behaves like this:

• When object entries are exported, the ERC of attachment field data (files) is included in the exported data.
  • If the attachment is at a different scope than the object, the scope is also included.
  • For attachments that were directly uploaded by the user and are hidden from the document library, the attachment cannot be made unless the file content is directly included in the exported object as base64 encoded data.
• When entries are imported, the ERC is used to reattach files.
  • If the attachment is already in the system, it’s added to the object entry on the fly.
  • If the attachment isn’t in the system, a dummy file (i.e., a shell) is created so the file link can be restored later when it’s imported.

Related Topics

• Consuming REST Services
• Consuming GraphQL APIs