Object Operations
Object Operations
Overview
This document provides a standardized framework for Create, Read, Update, and Delete (CRUD) operations applicable to a range of objects within the Rose Rocket application. The CRUD operations described here are designed to be consistent across all supported objects, ensuring a uniform API experience.
Supported Objects
The CRUD operations outlined in this guide apply to the following:
- Customer
- Order
- Task
- Address
- Commodities
- Manifest
- Tax Rate and Tax Rate Components
- Webhooks
Each object type follows the same set of attributes and behaviors for CRUD actions to allow these operations to be universally applied.
Navigate to the Guide
To effectively utilize the CRUD operations, it is recommended that you first familiarize yourself with the general syntax, common attributes or fields, and operations details provided in the subsequent sections. This enables you to understand the API requests and responses.
Once you have a grasp of the general syntax, you’re encouraged to view the Examples section located at the end of this document. The examples illustrate the application of CRUD operations using a Customer record, the concepts and code structures are directly transferable to other objects. You can adapt the example patterns to suit any of the supported objects.
Important: For detailed information on how to obtain and use the authentication bearer token, please refer to our OAuth 2.0 Authentication documentation.
Create
Create a new record for any one of the supported objects in our platform. Send a POST
request to /objects
with a request body that includes the data for the new record.
Additionally, related objects can also be created as part of the root object by including their data as attributes in the payload. For example, a task object will be created if included as an attribute for a new order.
HTTP request
All CRUD API requests should be made to the following base URL:
Base URL
POST <https://network.roserocket.com/api/v2/platformModel/objects>
Request header
All requests must include the following headers:
Name | Description |
---|---|
Content-Type | application/json |
Note: For more details on obtaining your bearer token, see our OAuth 2.0 Authentication Documentation.
Query parameters
Fields | Description |
---|---|
objectKey | The key that identified the type of object being created. For example, customer, order, task, manifest, and so on. |
json | The JSON payload contains the fields and values for the new object. |
Refer to the specific object's field documentation for details on what to include in the json payload.
Request Body
Provide the <objectKey>
to specify the key that identifies the type of object being created and include the new record data in json
format.
Sample Request
Below is a generic sample request structure for creating a new record.
curl --location --request POST '<https://network.roserocket.com/api/v2/platformModel/objects'>
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
"objectKey": "<objectKey>",
"json": {
"field1": "value1",
"field2": "value2",
// Additional fields as required by the object
"task": {
"name": "my connected task"
}
}
}'
- Replace <objectKey> and the json payload with the specific details for the object you are creating.
- Replace <token> with your API access token.
- If the
objectKey
wasorder
in the example above, and theorder
object contained atask
field, we could also create this in the same request by passing in thename
attribute of thetask
object
Sample Response
The response payload for a successful create operation will typically include details of the newly created record. Below is a generic representation of the response structure:
{
"id": "<uniqueIdentifier>",
"objectKey": "objectType",
"orgId": "<organizationId>",
"source": "<creationSource>",
"fullId": "<humanReadableIdentifier>",
// Additional object-specific fields go here
"createdAt": "<creationTimestamp>",
"createdBy": "<creatorUserID>",
"updatedAt": "<lastUpdateTimestamp>",
"updatedBy": "<lastUpdateUserId>",
"version": <versionNumber>
}
Read
Retrieve an existing record for any one of the supported objects in our platform. Send a GET request to /objects/{id}
with the object's unique identifier. By default, a GET request returns attributes that are directly related to the object. However, developers have the ability to fetch additional fields by using the "paths" query parameter.
HTTP request
All API requests should be made to the following base URL:
Base URL
GET <https://network.roserocket.com/api/v2/platformModel/objects/{id}>
Sample Request
Below is a generic sample request structure for retrieving an existing record.:
curl --location '<https://network.roserocket.com/api/v2/platformModel/objects/{id}'>
--header 'Authorization: Bearer <token>'
--data ''
Replace {id}
with the unique identifier of the object you want to retrieve.
Fetching additional fields with paths
To retrieve more detailed information, specify additional fields using the "paths" query parameter in your GET
request. This allows you to get related objects which are not included by default. You can request multiple paths by separating them with commas.
Sample Request with paths
curl --location '<https://network.roserocket.com/api/v2/platformModel/objects/{id}?objectKey=task&paths=commodities,relatedCommodities,stops'>
--header 'Authorization: Bearer <token>'
--data ''
Sample Response
The response payload for a successful GET operation will typically include details of the retrieved record. Below is a generic representation of the response structure:
{
"id": "<uniqueIdentifier>",
"objectKey": "<objectType>",
"orgId": "<organizationId>",
"source": "<creationSource>",
"fullId": "<humanReadableIdentifier>",
// Additional object-specific fields go here
"createdAt": "<creationTimestamp>",
"createdBy": "<creatorUserId>",
"updatedAt": "<lastUpdateTimestamp>",
"updatedBy": "<lastUpdaterUserId>",
"version": "<lastUpdaterUserId>",
// Additional requested paths
"commodities": "<Array of Commodities>",
"relatedCommodities": "<Array of related commodities>",
"stops": "<Array of stops>",
}
The fields in the response will contain actual data corresponding to the object that was requested, including any additional fields specified by the "paths" parameter.
To view the list of fields you can retrieve in each object, see the Standard Objects section.
Update
Modify an existing record for any one of the supported objects in our platform. The update operation can be performed using the PUT HTTP method.
PUT
Use the PUT method to update specific fields on a record. Send a PUT request with the object's unique identifier and the data to be updated.
HTTP request
All API requests should be made to the following base URL:
Base URL
PUT <https://network.roserocket.com/api/v2/platformModel/objects/{id}>
Replace <{id}>
with the unique identifier of the object you want to update. This id is a critical part of the URL, as it tells the API which specific object to modify.
Request body
Provide the <objectKey> to specify the key that identifies the type of object being updated and include the new object data in json format.
Sample Request
Below is a generic sample request structure for updating a record completely.
curl --location --request PUT '<https://network.roserocket.com/api/v2/platformModel/objects/{id}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
"objectKey": "<objectKey>",
"json": {
"field1": "value1",
"field2": "value2",
// Other fields go here
"task": {
"id": "<taskId>",
// Other task fields go here
}
}
}'
Replace <{id}>
with the actual ID of the object you want to update, <objectType>
with the appropriate object key, and include the updated data within the json object. If there is a connected object, you can also update their value by specifying their unique identifier. For example replace <taskId>
of the connected task you want to update.
Sample response
The response payload for a successful update operation will typically include details of the updated record. Below is a generic representation of the response structure:
{
"id": "<uniqueIdentifier>",
"objectKey": "objectType",
"orgId": "<organizationId>",
"source": "<creationSource>",
"fullId": "<humanReadableIdentifier>",
// Other updated object-specific fields go here
"externalId": null,
"createdAt": "<creationTimestamp>",
"createdBy": "<creatorUserID>",
"updatedAt": "<lastUpdateTimestamp>",
"updatedBy": "<lastUpdateUserId>",
"version": <versionNumber>
}
The response will include the updated record. The <externalId>
field may be null if an external identifier is not set for the object.
Delete
Remove an existing record for any one of the supported objects in our platform. Send a DELETE request with the object's unique identifier.
HTTP request
All API requests should be made to the following base URL:
Base URL
DELETE <https://network.roserocket.com/api/v2/platformModel/objects/{id}>
Request header
All requests must include the following headers:
Name | Description |
---|---|
Content-Type | application/json |
Authorization | Bearer <token> |
Sample request
Below is a generic sample request structure for deleting an existing record. Replace
{id}
with the unique identifier of the object you want to delete.
curl --location --request DELETE '<https://network.roserocket.com/api/v2/platformModel/objects/{id}'>
--header 'Authorization: Bearer <token>'
--data ''
- Replace
{id}
with the actual ID of the object you want to delete. - Replace
<token>
with the actual bearer token provided for API access.
Sample response
The response payload for a successful DELETE operation will typically include a confirmation that the object has been deleted. Below is a generic representation of the response structure:
{
"id": "<uniqueIdentifier>",
"objectKey": "<objectType>",
"orgId": "<organizationId>",
"source": "<creationSource>",
"fullId": "<humanReadableIdentifier>",
// Object-specific fields that were part of the deleted object may go here
"createdAt": "<creationTimestamp>",
"createdBy": "<creatorUserId>",
"updatedAt": "<lastUpdateTimestamp>",
"updatedBy": "<lastUpdaterUserId>",
"version": <versionNumber>
// Additional fields as applicable to the object type
}
Response Codes
Code | Message |
---|---|
200 OK | The object is successfully deleted, and a message is returned. |
204 No Content | The object is successfully deleted, and no content is returned. |
400 Bad Request | Invalid request parameter being sent. |
401 Unauthorized | The user is not authorized to access the resource, or the authentication token has expired. |
404 Not Found | No object found with the provided ID. |
500 Internal Server Error | The request cannot be processed. |
Examples
Create Customer record
Create a customer record.
Request
curl --location --request POST '<https://network.roserocket.com/api/v2/platformModel/objects'>
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
"objectKey": "customer",
"json": {
"name": "ABC Produce Co",
"companyEmail": "[[email protected]](mailto:[email protected])",
"companyPhone": "555-555-5555",
"customerType": "broker",
"busHoursMonStartAt": 32400,
"busHoursMonEndAt": 32401,
"busHoursTueStartAt": 32402,
"busHoursTueEndAt": 32403,
"busHoursWedStartAt": 32404,
"busHoursWedEndAt": 32405,
"busHoursThuStartAt": 32406,
"busHoursThuEndAt": 32407,
"busHoursFriStartAt": 32408,
"busHoursFriEndAt": 32409,
"busHoursSatStartAt": 32410,
"busHoursSatEndAt": 32411,
"busHoursSunStartAt": 32412,
"busHoursSunEndAt": 32413,
"defaultCurrency": "USD"
}
}'
Response
{
"id": "f4da5073-0b52-469f-97fe-fd30092fcfbe",
"objectKey": "customer",
"orgId": "e3127dc0-fc4d-4354-b65d-b3e846d80297",
"source": "manual",
"fullId": "CUST-18",
"name": "ABC Produce Co",
"status": "active",
"customerType": "broker",
"companyEmail": "[[email protected]](mailto:[email protected])",
"companyPhone": "555-555-5555",
"busHoursMonStartAt": 32400,
"busHoursMonEndAt": 32401,
"busHoursTueStartAt": 32402,
"busHoursTueEndAt": 32403,
"busHoursWedStartAt": 32404,
"busHoursWedEndAt": 32405,
"busHoursThuStartAt": 32406,
"busHoursThuEndAt": 32407,
"busHoursFriStartAt": 32408,
"busHoursFriEndAt": 32409,
"busHoursSatStartAt": 32410,
"busHoursSatEndAt": 32411,
"busHoursSunStartAt": 32412,
"busHoursSunEndAt": 32413,
"defaultCurrency": "USD",
"mapMarkers": [],
"formattedBusinessHours": "Monday - 09:00-09:00, Tuesday - 09:00-09:00, Wednesday - 09:00-09:00, Thursday - 09:00-09:00, Friday - 09:00-09:00, Saturday - 09:00-09:00, Sunday - 09:00-09:00",
"createdAt": "2024-04-02T14:52:26.409Z",
"createdBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"updatedAt": "2024-04-02T14:52:26.409Z",
"updatedBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"version": 1
}
Get Customer record
Retrieves the customer record.
Request
curl --location '<https://network.roserocket.com/api/v2/platformModel/objects/f4da5073-0b52-469f-97fe-fd30092fcfbe'>
--header 'Authorization: Bearer <token>'
--data ''
Response
{
"id": "f4da5073-0b52-469f-97fe-fd30092fcfbe",
"objectKey": "customer",
"orgId": "e3127dc0-fc4d-4354-b65d-b3e846d80297",
"source": "manual",
"fullId": "CUST-18",
"name": "ABC Produce Co",
"status": "active",
"customerType": "broker",
"companyEmail": "[[email protected]](mailto:[email protected])",
"companyPhone": "555-555-5555",
"busHoursMonStartAt": 32400,
"busHoursMonEndAt": 32401,
"busHoursTueStartAt": 32402,
"busHoursTueEndAt": 32403,
"busHoursWedStartAt": 32404,
"busHoursWedEndAt": 32405,
"busHoursThuStartAt": 32406,
"busHoursThuEndAt": 32407,
"busHoursFriStartAt": 32408,
"busHoursFriEndAt": 32409,
"busHoursSatStartAt": 32410,
"busHoursSatEndAt": 32411,
"busHoursSunStartAt": 32412,
"busHoursSunEndAt": 32413,
"defaultCurrency": "USD",
"mapMarkers": [],
"formattedBusinessHours": "Monday - 09:00-09:00, Tuesday - 09:00-09:00, Wednesday - 09:00-09:00, Thursday - 09:00-09:00, Friday - 09:00-09:00, Saturday - 09:00-09:00, Sunday - 09:00-09:00",
"externalId": null,
"createdAt": "2024-04-02T14:52:26.409Z",
"createdBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"updatedAt": "2024-04-02T14:52:26.409Z",
"updatedBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"version": 1
}
Update Customer record
PUT
Modify the existing record completely. Customer ID to be passed as url param in request body.
Request
curl --location --request PUT '<https://network.roserocket.com/api/v2/platformModel/objects/df70da0f-8f0e-4cd5-ad8e-cd4557205f63'>
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
"objectKey": "customer",
"json": {
"name": "ABC Produce Co"
}
}'
Response
{
"id": "df70da0f-8f0e-4cd5-ad8e-cd4557205f63",
"objectKey": "customer",
"orgId": "e3127dc0-fc4d-4354-b65d-b3e846d80297",
"source": "manual",
"fullId": "CUST-21",
"name": "ABC Produce Co",
"status": "active",
"companyEmail": "[[email protected]](mailto:[email protected])",
"defaultCurrency": "USD",
"mapMarkers": [],
"externalId": null,
"createdAt": "2024-04-02T15:06:11.025Z",
"createdBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"updatedAt": "2024-04-02T15:11:54.980Z",
"updatedBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"version": 2
}
Delete Customer record
Delete a customer record using the specific object id of the object you want to delete.
Request
curl --location --request DELETE '<https://network.roserocket.com/api/v2/platformModel/objects/02624b9c-22cf-47a2-bbc2-83939d378faa'>
--header 'Authorization: Bearer <token>'
--data ''
Response
{
"id": "02624b9c-22cf-47a2-bbc2-83939d378faa",
"objectKey": "customer",
"orgId": "e3127dc0-fc4d-4354-b65d-b3e846d80297",
"source": "manual",
"fullId": "CUST-19",
"name": "ABC Produce Co",
"status": "active",
"customerType": "shipper",
"defaultCurrency": "USD",
"externalId": null,
"createdAt": "2024-04-02T14:54:43.587Z",
"createdBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"updatedAt": "2024-04-02T14:54:43.587Z",
"updatedBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
"version": 1
}
Updated about 1 month ago