API ENDPOINT - Serialized Experience & Registration Management

Summary

Serialized experiences allow for 1:1 registration, with unique URLs per individual experience, a product or potential registration can be "claimed" by a customer. QR codes can either be unique and lead directly to the serialized experience, or a single QR code can be used leading to a Serial Number Router that directs customers to their unique experience based on a serial number they input.

The Serialization API enables your external systems to manage the lifecycle of serialized product experiences. This includes generating serialized codes, removing ownership, swapping serial numbers of an existing owner, and looking up customer data. The API is designed for seamless integration with manufacturing, ERP, logistics, and customer service systems like Zendesk.

Overall Process Outline

1. Build experience & at least one variant in Brij
   1. ensure variant has SKU/Product ID filled out at the variant level, if you will be using this in the API as the identifier. If there are multiple variants under one experience, do not share SKU with the parent experience so SKU can be different per variant.
      1. Parent and variant experiences can be imported in bulk within Brij. When importing, be sure to NOT share with parent if there are multiple variants under the parent, so the SKU can be different per variant.
   2. You can also use the Brij Experience ID instead of SKU to identify which variant experience to add serial numbers to, via the API.
2. Add serialized codes to Variant - either through API or in Brij platform
   1. See API endpoint 1 below

When sending “experienceID” in any of the endpoints below, always use the Variant Experience ID since serial numbers are always attached to a Variant Experience.

Similarly, if sending “productSku” instead, ensure that the correct SKU is saved on the variant experience, and not duplicated on any other experience including it’s parent.

1. Serialized Code Import

Endpoint: POST {{Base_URL}}/experiences/serialization

Purpose: Generate unique Brij experiences linked to each serialized product identifiers.

Batch Support: Create up to 10,000 experiences in a single request.

Request Example

json

[
  {
    "serialNumber": "XYZ123456789",
    "experienceId": "ABC123"
  },
  {
    "serialNumber": "XYZ987654321",
    "productSku": "ABC-1000"
  }
]

Response Example

  {
    "serialNumber": "XYZ123456789",
    "experienceId": "ABCDEFGH12345678",
    "experienceUrl": "<https://brij.it/c/ABCDEFGH2345678>"
  }
]

[
  {
    "serialNumber": "XYZ123456789",
    "experienceId": "ABC123",
    "experienceUrl": "<https://brij.it/c/ABCDEFGH2345678>"
  }
]

// Sample error responses
[
  // Brij experience ID not found
  {
    "errorMessage": "Brij experience ID ABC123 not found. To enter a serial number you must have an associated Brij experience and variant. Brij experiences are created directly in the Brij platform, and cannot be created programmatically"
    "serialNumber": "XYZ123456789",
    "experienceId": "ABC123",
  },
  // Brij product SKU not found
  {
    "errorMessage": "Brij product SKU ABC-1000 not found. To enter a serial number you must have an associated Brij product and variant. Brij products and variants are created directly in the Brij platform, and cannot be created programmatically"
    "serialNumber": "XYZ123456789",
    "productSku": "ABC-1000",
  },
  // Serial number format error
  {
    "errorMessage": "The serial number is too long, etc... must be less than x characters etc...."
    "serialNumber": "XYZ123456789999999999999999",
    "productSku": "ABC-1000",
  },
  // The serial number already exists
  {
    "errorMessage": "The serial number already exists"
    "serialNumber": "XYZ123456789",
    "productSku": "ABC-1000",
  },
    // The > 10k
  {
    "errorMessage": "You must submit less than 10,000 serials per request"
    "serialNumber": "XYZ123456789",
    "productSku": "ABC-1000",
  },
]

2. Reset Registered Serial Number

Endpoint: DELETE {{Base_URL}}/registrations

Purpose: Reset a previously registered product, clearing associated customer data so the Serial number can be registered again.

Request Example

{	
  "serialNumber": "XYZ123456789"
}

Response Example

{
  "message": "Serial number XYZ123456789 has been reset successfully."
}

// Sample error responses
{
  "message": "Serial number XYZ123456789 not found."
},
{
  "message": "Serial number XYZ123456789 not registered."
},

3. Update Serial Number for Existing Registration

Endpoint: PUT {{Base_URL}}/registrations

Purpose: Update the serial number of a registered product while preserving ownership and history.

Request Example

{
  "operation": "update-serial",
  "oldSerialNumber": "XYZ123456789",
  "newSerialNumber": "XYZ111222333"
}

Response Example

{
  "message": "Serial number updated from XYZ123456789 to XYZ111222333."
}

// Sample error responses
{
  "message": "Serial number updated from XYZ123456789 to XYZ111222333."
},
{
  "message": "Serial number XYZ123456789 not found."
},
{
  "message": "The serial number XYZ111222333 is too long, etc... must be less than x characters etc...."
},
{
  "message": "unknown operation, only update-serial is allowed"
},
{
  "message": "The serial number XYZ111222333 already exists and has been registered"
}

4. Retrieve Registration Data by Serial Number

Endpoint: GET {{Base_URL}}/registrations/:serialNumber

Purpose: Fetch product registration and customer data by serial number.

Sample Response

{
  "serialNumber": "XYZ123456789",
  "customer": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "555-123-4567"
  },
  "registration": {
    "timestamp": "2025-04-14T10:30:00Z",
    "status": "Registered"
  },
  "experience": {
    "sku": "ABC-1000",
    "url": "<https://brij.it/c/ABCDEFGH2345678>"
  }
}

// Sample error responses
{
  "message": "Serial number XYZ123456789 not found."
},
{
  "message": "Serial number XYZ123456789 has not been registered"
},

🗂 Data Models

Experience Object

• serialNumber: string
• brijId or productSku: string (one required)
• experienceId: string
• experienceUrl: string

Customer Object

• name: string
• email: string
• phone: string

❗ Error Handling