Guides

Getting Started with the Rose Rocket API

Learn more about Rose Rocket’s API in this walkthrough to get started.

Suggest Edits

Overview

This Getting Started tutorial is a walkthrough for the overall experience from start to finish using the Rose Rocket API. This guide covers account set up, authenticating your credentials, making your first Rose Rocket request, and then sharing next steps for your integration.

Prerequisites

To start, confirm you have the prerequisites below before continuing.

  • Rose Rocket account with access to the Developer Portal, reach out to your account representative for more information
  • Redirect URI for your application

Authenticating

Authenticating in Rose Rocket is for confirming you and your account identity. The Client ID and the Client Secret are important credential values to authorize your application when making requests. These act as the security values to make sure your application and your account are linked together and the connection is protected.

To retrieve these, you have to create a new application under the API settings section in your Account Settings. Navigate to OAuth Applications and select Create New Application. This creates a new application for you to name. In your new application, you have the Client ID and the Client Secret. The end result of the authentication process is a Bearer Token, or an access token. Use this value to make authenticated requests against the Rose Rocket API.

Configuring the OAuth Application section

To begin your authentication, create an OAuth application. This is for authenticating users and delivering access tokens for API requests.

The OAuth Applications section has a table that also displays the Redirect URIs for your application. This column is for the callback URL to validate your application and then collect an access token. When your application completes the callback validation, you’ll receive a Token with OAuth 2.0 to set up your authorization.

For a complete guide on authentication, see the Authentication Guide to access Rose Rocket with OAuth 2.0.

Getting an access token

To retrieve your access token, set up your authorization request. This example uses Postman configurations to get a new access token. Follow the steps below to configure your new token request.

  1. Set up Callback URL.
  2. Add Auth URL for Rose Rocket: https://a.roserocket.com/authorize
  3. Add Access Token URL: https://a.roserocket.com/oauth/token
  4. Add the Client ID.
  5. Add the Client Secret.
  6. Set Auth Request key value pairs: audience = https://roserocket.com
  7. Set Token Request key value pairs: audience = https://roserocket.com Send in Request body.
  8. Select Get New Access Token.
  9. Proceed through the OAuth 2.0 authorization prompts from the callback URL to collect your access token.

This list below has example values for the credentials.

  • Client ID - Mv2aYbhFSDRSZYoxbARqI6pY1MzXqleZ
  • Client Secret - EwgCIa3tTRSTEsQlvsIArFO8vqFhZTaPJ-3xStegrHwcKLBVLFLrgi4yTK1JvxQq
  • OAuth 2.0 Token - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Making requests

Your application can begin making requests with the correct credentials in place, in this case the OAuth 2.0 bearer token, or access token as your authorization moving forward. Using the token, you can then make API requests to Rose Rocket with the value in the HTTP authorization header. Your authenticated application can create, read, update, and delete objects in your account.

Create a new customer

This tutorial covers the first request of creating a new customer. In Rose Rocket, customer data is required to add new objects such as orders and quotes. Use the customerID value whenever referencing this object.

The code sample below is a cURL request for creating a new customer in an account.

curl --location --request PATCH 'https://network.roserocket.com/api/v2/platformModel/objects' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{"boardId":"af1c0e83-5253-517d-aeff-e25a37f59beb","objectKey":"customer","json":{
   "name": "XYZ Freight Corp",
   "address": "123 Main St",
   "city": "New York",
   "state": "New York",
   "postal": "10001",
   "currency": "usd"
}}'

After sending the request, the response should be 200, indicating that the operation was successful. You can then collect the ID from the payload to refer to this sample customer.

Retrieve customer information

In this next section, this guide covers retrieving information about this specific new customer. The Get customer by ID endpoint requires the ID value. Use that value to replace the {{objectID}} in the request URL and retrieve all of the information about this customer. View the sample request below.

curl --location 'https://network.roserocket.com/api/v2/platformModel/objects/{{objectID}}' \
--header 'Authorization: ••••••'

The response for a successful request is 200 and has the response body payload with all of the information about that customer. See the response below.

{
    "id": "e54225d7-3bc9-4803-992a-af107b0db8df",
    "objectKey": "customer",
    "orgId": "2c39fa07-b82c-493f-8ec8-996cd0618612",
    "source": "manual",
    "widgets": [
        {
            "key": "platformCustomer-AddCompanyDetails",
            "name": "CreateCustomer",
            "version": 0
        },
        {
            "key": "customer-ETADelayNotifications",
            "name": "ETADelayNotifications",
            "version": 0
        },
        {
            "key": "platformCustomer-EditCommissionedUsers",
            "name": "EditCommissionedUsers",
            "version": 0
        }
    ],
    "widgetToOpen": {
        "key": "platformCustomer-AddCompanyDetails",
        "name": "CreateCustomer",
        "version": 0
    },
    "fullId": "CUST-9",
    "name": "XYZ Freight Corp",
    "status": "active",
    "mapMarkers": [],
    "externalId": null,
    "createdAt": "2024-05-28T21:59:53.201Z",
    "createdBy": "bfcf84aa-55d4-4d58-a8d6-871f0d462a04",
    "updatedAt": "2024-05-28T21:59:53.201Z",
    "updatedBy": "bfcf84aa-55d4-4d58-a8d6-871f0d462a04",
    "version": 1,
    "etaDelayNotifyEnabled": true,
    "etaDelayNotifyLabel": "Enabled"
}

All of the information from the first API request creating the new customer is visible in the response for retrieving the customer’s information.

Summary

Congratulations, you’ve made your first Rose Rocket request! In this tutorial, you’ve authenticated your credentials to make valid API requests, created a new customer using the Create a new customer endpoint, and then retrieved that customer’s information afterwards.

Next steps

With this process complete, you can make other requests and start to increase the scale and complexity of your integration with Rose Rocket. View the suggestions below for next steps in your workflows.

  • Create a new order for a customer
  • Update a customer's information
  • Add a partner carrier
  • Set nested objects
  • Query objects using paths

Updated 9 days ago