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 |
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 |
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 "test@liferay.com: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+
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:
-
A
nestedFieldsJSON object specifying the related object’s ID ("id"). -
A
nestedFieldsJSON object specifying the related object’s external reference code ("externalReferenceCode"). -
The related object’s ID.
-
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.