Updating Resources with RAVE Connections

31 min

RAVE Connections let you keep your Paccurate Resource Library in sync with external data sources — whether that's a dimensioning system like Qboid, a WMS, an ERP, or any REST API that can return JSON. Once a connection is configured, you can pull data in on a schedule, trigger an import manually, or push data directly via the RAVE REST API.

RAVE Connections are available to Premium & Enterprise plans only. Please reach out to your customer success manager to enable them on your account

This guide walks through setting up a connection, understanding how data is mapped, and using the API to read and write resource data.

What is a RAVE Connection?

A RAVE Connection is a bridge between an external data source and a Paccurate Resource Library list (Items, Cartons, or Orders). Each connection defines:

Where to pull data from (a third-party API endpoint)

How to authenticate with that source

How to translate the incoming data fields into Paccurate resource fields (Schema Map)

When to run automatically (scheduling)

Which resource to create or update

Each connection also generates its own API credentials, enabling direct programmatic writes to the resource without going through the third-party source at all.

RAVE is an acronym for “Really Awesome Value Extractor” — Paccurate decided to keep the working name because our customers are awesome, and so is their data.

Step 1 — Create a Connection

Navigate to your plan's RAVE Connections page:

https://manage.paccurate.io/plans/<plan_id>/rave-connections

Click New Rave Connection to open the connection editor.

General Settings

Field	Description
Name	A short, descriptive label for this connection
Account	Which Paccurate account to use for resource access
Resource Type	The type of resource to populate: items, cartons, or orders
New Resource Base Name	Prefix used when creating a new resource (e.g. qboid_items)
Resource to Update	Leave blank to always create a new resource, or select an existing resource to overwrite/update it on each sync

Connection Details

This section tells Paccurate where to pull data from and how to authenticate with the external source.

Field	Description
Third-Party API URL	The fully qualified endpoint URL that returns the source data
Third-Party API Key	Stored credential, accessible as {{ api_key }} in the headers template
Third-Party API Token	Stored credential, accessible as {{ api_token }} in the headers template
API Headers Template	Valid JSON sent as headers on each webhook request. Use {{ api_key }} and {{ api_token }} as placeholders.

Example headers template:

{ "Authorization": "Bearer {{ api_token }}", "X-Api-Key": "{{ api_key }}" }

Step 2 — Map Your Data

This is where you tell Paccurate how to translate fields from your external source into resource properties.

Schema Root Path

The name of the top-level property in the API response that contains the array of records to import. For example, if the API returns:

{ "scans": [ { "id": 1, "l": 10, "w": 8, "h": 6 } ] }

…then your Schema Root Path is scans.

Schema Map

A JSON object where each key is a Paccurate resource property and each value is the corresponding field name in your source data. Dot notation is supported for nested fields.

Format:

{ "<paccurate_property>": "<source_field>" }

Example (Qboid → Paccurate Items):

{
  "refId": "id",
  "weight": "weight",
  "sequence": "barcode",
  "dimensions_x": "h",
  "dimensions_y": "w",
  "dimensions_z": "l",
  "properties.batt": "attributes.batt",
  "properties.fold": "attributes.fold item",
  "properties.frgl": "attributes.frgl",
  "properties.hazmat": "attributes.hazmat"
}

Available Paccurate Item Properties

Property	Required	Type
refId	✅ Yes	integer or string
dimensions_x	✅ Yes	float
dimensions_y	✅ Yes	float
dimensions_z	✅ Yes	float
weight	No	float
name	No	string
color	No	string
sequence	No	string
properties	No	JSON object

Step 3 — Set a Schedule (Optional)

If you want Paccurate to automatically pull from the external source on a recurring basis, configure scheduling:

Field	Description
Start Date & Time	The first time the sync should run; all future runs are calculated from this baseline
Sync Frequency	Hourly, Daily, Weekly, or Monthly

If you don't need automatic scheduling, you can skip this and trigger syncs manually or via the API.

Step 4 — Save and Get Your API Secret

Click Create. After saving, Paccurate will generate an API Secret for this connection.

⚠️ Copy your secret immediately. It will not be shown again. The first 10 characters (the secret stem) are saved and displayed in the editor so you can confirm which secret is active.

You can regenerate credentials at any time from the connection editor. Regenerating immediately invalidates the previous values.

Triggering an Import Manually

To run a one-time pull from the third-party source:

Open the connection in PacManage

Go to Connection Details

Click Trigger Webhook

After the import runs, check the connection log to confirm success and see how many records were processed. Newly imported resources appear in the Resource Library under the applicable type (Items, Cartons, Orders), prefixed with the New Resource Base Name you set.

Unit Conversions

The RAVE REST API supports automatic unit conversion during data ingestion. Pass conversion parameters as URL parameters or request headers on any POST, PUT, or PATCH request. Conversions are applied after the schema map is evaluated, so values are stored already in the converted unit.

Parameter	Header	Values	Converts
dim_conv	X-Paccurate-Dim-Conv	mm_to_in, in_to_mm	dimensions_x/y/z
weight_conv	X-Paccurate-Weight-Conv	gr_to_lb, lb_to_gr	weight

Example URL:

https://manage.paccurate.io/rave-api/your_public_api_id/rest?dim_conv=mm_to_in&weight_conv=gr_to_lb

Using the RAVE REST API

In addition to scheduled and manual webhook imports, each RAVE Connection exposes a REST API that lets you push data directly into a resource — no third-party source required. This is useful for integrations where your system wants to send data to Paccurate in real time.

Authentication

Pass your API Secret on every request using one of two methods:

URL parameter:

?pac_api_secret=your_secret_here

Request header:

X-Paccurate-API-Secret: your_secret_here

Base URLs

Purpose	URL
Trigger webhook import	https://manage.paccurate.io/rave-api/{public_api_id}/webhook
Direct resource manipulation	https://manage.paccurate.io/rave-api/{public_api_id}/rest

API Reference

GET — Trigger Webhook Import

Triggers a pull from the third-party API URL configured in Connection Details and imports the result into the connected resource. Behaves identically to clicking Trigger Webhook in PacManage.

If Resource to Update is blank → creates a new resource

If Resource to Update is set → overwrites that resource with the imported data

Endpoint: GET /rave-api/{public_api_id}/webhook

POST — Create or Upsert

Send data directly to create a new resource or upsert rows into an existing one.

No Resource to Update set → creates a new resource from the payload

Resource to Update set → upserts into the existing resource (same behavior as PATCH)

Endpoint: POST /rave-api/{public_api_id}/rest

Response:

{ "packResourceId": 12345, "status": "success" }

Create a new resource with a single item:

{
  "payload": {
    "id": 325144,
    "l": 111,
    "w": 106,
    "h": 10,
    "weight": 55793,
    "barcode": "",
    "attributes": { "stackable": "yes" }
  }
}

Create a new resource with multiple items:

{
  "payload": [
    {
      "id": 325144,
      "l": 111,
      "w": 106,
      "h": 10,
      "weight": 55793,
      "attributes": { "stackable": "yes" }
    },
    {
      "id": 325053,
      "l": 240,
      "w": 170,
      "h": 87,
      "barcode": "0901B001",
      "attributes": { "foldable": true }
    }
  ]
}

Upsert into an existing resource (with row matching):

Use row_key to specify which field(s) should be used to match incoming rows against existing rows. Use mapped property names (e.g. refId, not id). Matched rows are updated; unmatched rows are inserted.

{
  "payload": [
    {
      "id": 325144,
      "weight": 50,
      "attributes": { "foldable": true }
    },
    {
      "id": 325053,
      "weight": 100,
      "attributes": { "foldable": true }
    },
    {
      "id": 325131,
      "l": 141,
      "w": 49,
      "h": 32,
      "barcode": "",
      "attributes": { "other": "orientation lock" }
    }
  ],
  "row_key": ["refId"]
}

In this example, the first two records exist in the resource and will be updated. The third is new and will be inserted — which is why it requires a full/complete object.

PUT — Overwrite

Replaces the entire contents of an existing resource with the payload data. Resource to Update must be set.

Payload must be an array of complete objects (no partial records)

All existing rows are removed before the new data is written

Endpoint: PUT /rave-api/{public_api_id}/rest

Response:

{ "status": "success" }

Overwrite a resource with three items:

{
  "payload": [
    {
      "id": 325144,
      "l": 111,
      "w": 106,
      "h": 10,
      "weight": 55793,
      "barcode": "",
      "attributes": { "stack item": "ruleneeded" }
    },
    {
      "id": 325053,
      "l": 240,
      "w": 170,
      "h": 87,
      "barcode": "0901B001",
      "attributes": { "stack item": "internalspace" }
    },
    {
      "id": 325131,
      "l": 141,
      "w": 49,
      "h": 32,
      "barcode": "",
      "attributes": { "other": "orientation lock" }
    }
  ]
}

PATCH — Upsert / Append

Adds or merges rows into an existing resource without clearing it first. Resource to Update must be set.

With row_key: incoming rows are matched against existing rows. Matches are merged; non-matches are inserted as new rows.

Without row_key: all incoming rows are appended to the end of the resource without any deduplication.

row_key can be passed three ways:

Method	Example
Body property	"row_key": ["refId"]
URL parameter	?row_key=["refId"]
Header	X-Paccurate-Rave-Row-Key: ["refId"]

Endpoint: PATCH /rave-api/{public_api_id}/rest

Response:

{ "status": "success" }

Upsert with row matching:

{
  "payload": [
    {
      "id": 325144,
      "weight": 50,
      "attributes": { "foldable": true }
    },
    {
      "id": 325053,
      "weight": 100,
      "attributes": { "foldable": true }
    },
    {
      "id": 325131,
      "l": 141,
      "w": 49,
      "h": 32,
      "barcode": "",
      "attributes": { "other": "orientation lock" }
    }
  ],
  "row_key": ["refId"]
}

Append without matching (no row_key):

{
  "payload": [
    {
      "id": 325999,
      "l": 50,
      "w": 40,
      "h": 20,
      "weight": 1000,
      "barcode": "NEW-ITEM-001",
      "attributes": {}
    }
  ]
}

Response Codes & Errors

Applies to all POST, PUT, and PATCH requests to /rave-api/{public_api_id}/rest.

HTTP Status	Response Body	When It Happens
200 OK	{ "status": "success" } (POST also includes "packResourceId")	The write completed successfully.
200 OK	{ "status": "failure" } (POST also includes "packResourceId": null)	The request was authenticated but the write didn't complete — e.g. Resource to Update isn't set for PUT/PATCH, or the upsert/overwrite failed internally. Check the connection log for details.
400 Bad Request	{ "error": "Invalid JSON payload" }	payload could not be parsed as JSON.
400 Bad Request	{ "error": "Invalid row_key format" }	row_key (body, URL parameter, or header) was not a string or a JSON array.
401 Unauthorized	{ "error": "Unauthorized" }	The API Secret is missing, incorrect, or doesn't match the public_api_id in the URL.

⚠️ A 200 response does not guarantee the write succeeded — always check the status field in the response body, not just the HTTP status code.

Quick Reference: Which Action Should I Use?

Goal	Method
Pull from external API (scheduled or manual)	GET /webhook
Create a brand new resource from scratch	POST /rest (no Resource to Update set)
Replace everything in a resource	PUT /rest
Add new rows without touching existing rows	PATCH /rest (no row_key)
Update specific rows by matching key, insert new	PATCH /rest with row_key
Update specific rows or insert, via POST	POST /rest with row_key and Resource to Update set