COMMON WORKFLOWS

Think in business workflows, not endpoint lists.

These recipes show the usual order in which API calls are made. Start with the happy path, then use the full endpoint guide when you need exact field-level details.

Create a Sales OrderTrack an Order

Workflow 1 — Explore what is available

1. Get available devices, projects, and kits

GET https://workspace-stage.connectuscorp.com/api/v2/client/available_devices

This endpoint is useful for a quick account-level availability snapshot. Its response groups devices, projects, and kits.

2. List detailed projects

GET https://workspace-stage.connectuscorp.com/api/v2/client/projects

3. List kits for a project

GET https://workspace-stage.connectuscorp.com/api/v2/client/projects/PROJECT_ID/kits

4. List assembled instances of a kit

GET https://workspace-stage.connectuscorp.com/api/v2/client/kits/KIT_ID/assembled

Workflow 2 — Create a Sales Order

Step 1. Retrieve shipping methods

curl --request GET \
  --url "https://workspace-stage.connectuscorp.com/api/v2/client/available_shipping_methods" \
  --header "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  --header "Accept: application/json"

The response returns shipping method IDs and names. Use the returned name when you supply shipping_method.

Step 2. Prepare your order

The OpenAPI schema requires two top-level fields: customer_po_no and at least one item containing sku and quantity.

{
  "customer_po_no": "PO-2026-001",
  "items": [
    {
      "sku": "STR-12345",
      "quantity": 2
    }
  ]
}

Step 3. Add shipping and optional business data when needed

{
  "customer_po_no": "PO-2026-001",
  "items": [
    { "sku": "STR-12345", "quantity": 2 }
  ],
  "ship_address": {
    "name_company": "Example Company",
    "street": "123 S 400",
    "floor_suite": "Suite D",
    "city": "Chicago",
    "state": "IL",
    "zip": "60007",
    "country": "US",
    "email": "recipient@example.com",
    "contact": "Main User"
  },
  "shipping_method": "FedEx Ground Home Delivery - RPHD",
  "shipping_instructions": "Leave at the front desk",
  "custom_fields": {
    "project_name": "Project Alpha",
    "kit_name": "Starter Kit",
    "shipping_insurance": true
  }
}

If you include custom_fields, the current API schema requires project_name.

Step 4. Submit the order

curl --request POST \
  --url "https://workspace-stage.connectuscorp.com/api/v2/client/sales_order" \
  --header "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Request-ID: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{
    "customer_po_no": "PO-2026-001",
    "items": [{"sku":"STR-12345","quantity":2}]
  }'

A successful creation returns HTTP 201:

{
  "message": "Sales Order Created Successfully",
  "sales_order_number": "SO-00001",
  "customer_po_no": "PO-2026-001"
}

Step 5. Find the order by your PO number

curl --request POST \
  --url "https://workspace-stage.connectuscorp.com/api/v2/client/search_sales_orders?customer_po_no=PO-2026-001" \
  --header "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  --header "Accept: application/json"

Search results include the ConnectUs Sales Order id. Store that ID if you want to use the detailed Sales Order endpoint.

Workflow 3 — Track an existing Sales Order

Workflow 4 — Search by Sales Order status

First retrieve the currently active status IDs:

GET https://workspace-stage.connectuscorp.com/api/v2/client/sales_order_statuses

Then search Sales Orders using one or more status IDs:

POST https://workspace-stage.connectuscorp.com/api/v2/client/search_sales_orders?so_status[]=20&so_status[]=30