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 /object 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 <http://network.roserocket.com/api/v2/platformModel/objects>

Request header

All requests must include the following headers:

Name	Description
Content-Type	application/json
Authorization	Bearer

Note: For more details on obtaining your bearer token, see our OAuth 2.0 Authentication Documentation.
Query parameters

Fields	Description
id	Unique identifier of the object.
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 PATCH '<https://network.roserocket.com/api/v2/platformModel/objects'>
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
    "id": "<objectID>",
    "objectKey": "<objectKey>",
    "json": {
        "field1": "value1",
        "field2": "value2",
       // Additional fields as required by the object
    }
}'

Replace and the json payload with the specific details for the object you are creating.
Replace with your API access token.

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 either the PUT or PATCH HTTP method, depending on the requirements.

PUT

Use the PUT method to update an entire record. This method replaces the entire record with the new data provided in the request body. Send a PUT request with the object's unique identifier and the updated data.

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 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 '{
    "id": "<objectID>",
    "objectKey": "<objectKey>",
    "json": {
        "field1": "value1",
        "field2": "value2",
       // Other 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.

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 field may be null if an external identifier is not set for the object.

PATCH

Use the PATCH method to update specific fields of an object. Send a PATCH request with the object's unique identifier and only the fields that need to be updated:

HTTP request

All API requests should be made to the following base URL:

Base URL
PATCH <https://network.roserocket.com/api/v2/platformModel/objects>

Request body

Provide the to specify the key that identifies the type of object being updated and include only the fields that need to be updated.

Sample Request

curl --location --request PATCH '<https://network.roserocket.com/api/v2/platformModel/objects'>
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
    "id": "f4da5073-0b52-469f-97fe-fd30092fcfbe",
    "objectKey": "<objectKey>",
    "json": {
        // Update object-specific fields here
    }
}'

Replace {ID} with the actual ID of the object you want to update.
Replace with the actual bearer token provided for API access.
Replace with the key that identifies the type of object you are updating (e.g., customer, order
Include only the fields you wish to update within the json object.

Sample Response

The response payload for a successful update operation will typically include details of the updated record with the updated fields. Below is a generic representation of the response structure:

{
    "id": "<uniqueIdentifier>",
    "objectKey": "objectType",
    "orgId": "<organizationId>",
    "source": "<creationSource>",
    "fullId": "<humanReadableIdentifier>",
    // Updated object-specific fields go here
    "externalId": null,
    "createdAt": "<creationTimestamp>",
    "createdBy": "<creatorUserID>",
    "updatedAt": "<lastUpdateTimestamp>",
    "updatedBy": "<lastUpdateUserId>",
    "version": <versionNumber>
}

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

Query parameters

Fields	Description
`id`	Unique identifier of the object.
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.

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 PATCH '<https://network.roserocket.com/api/v2/platformModel/objects'>
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
    "id": "3d3acb3d-4aa0-443f-9793-0f9dd9547c4d",
    "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 '{
    "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
}

PATCH

Update the specific fields.

Request

curl --location --request PATCH '<https://network.roserocket.com/api/v2/platformModel/objects'>
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{
    "id": "f4da5073-0b52-469f-97fe-fd30092fcfbe",
    "objectKey": "customer",
    "json": {
        "name": "ABC Produce Co",
        "companyEmail": "[[email protected]](mailto:[email protected])",
        "defaultCurrency": "USD"
    }
}'

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": \[],
    "createdAt": "2024-04-02T15:06:11.025Z",
    "createdBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
    "updatedAt": "2024-04-02T15:06:11.025Z",
    "updatedBy": "d0235096-8c31-4212-8b0a-fbf1bd5bd00c",
    "version": 1
}

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
}