Guides

Object Descriptions & Operations

Suggest Edits

Object descriptions

Learn about Rose Rocket objects and how they work.

Rose Rocket objects behave in a similar way to any API object, with two specific distinctions. Connected objects and Read-only fields have additional functionality for streamlining your integration. View the sections below for more information.

Connected objects

The Rose Rocket API uses Connected objects within the object structures. These behave in the same way as other objects with an additional dependency. To retrieve values from connected objects, the request must include the specific ID value of that object. To view the values in the child object, use that ID value as a path parameter.

NOTE

If you’re not doing anything to the child objects when they’re connected, then you don’t need to add the path.

Read-only fields

Read-only fields are immutable values and cannot be written to. These fields have implicit dependencies and are derived from specific objects. If a field is derived from another, it is immutable and is read-only.

For example, the subTotal value in the Invoices object has a dependency on the lineItems attribute. The value for subTotal cannot be written to as it calculates the total of the financial line items connected to the invoice without including tax. In this case, the field is read-only because it’s derived from the collection of items within the lineItems object.

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
  • Webhooks
  • Partner
  • Quotes
  • Financial Line Item
  • Invoices
  • Tags
  • Assets
  • Bills
  • Contacts
  • Tax Rate and Tax Rate Components

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:

NameDescription
Content-Typeapplication/json
AuthorizationBearer

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

FieldsDescription
idUnique identifier of the object.
objectKeyThe key that identified the type of object being created. For example, customer, order, task, manifest, and so on.
jsonThe 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:

NameDescription
Content-Typeapplication/json
AuthorizationBearer

Query parameters

FieldsDescription
idUnique identifier of the object.
objectKeyThe key that identified the type of object being created. For example, customer, order, task, manifest, and so on.
jsonThe 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

CodeMessage
200 OKThe object is successfully deleted, and a message is returned.
204 No ContentThe object is successfully deleted, and no content is returned.
400 Bad RequestInvalid request parameter being sent.
401 UnauthorizedThe user is not authorized to access the resource, or the authentication token has expired.
404 Not FoundNo object found with the provided ID.
500 Internal Server ErrorThe 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
}

Updated 3 months ago