Create Object

Objects are the core entities in G2C Platform that represent physical or digital assets with complete blockchain-based audit trails.

Objects must be created within an existing subcategory. Each object requires a unique external ID within the company scope. Your company is automatically determined from your API key.

Endpoint

curl -X POST "https://api.g2cplatform.com/v2/categories/{CATEGORY_ID}/subcategories/{SUBCATEGORY_ID}/objects" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "LAPTOP-001",
    "name": "MacBook Pro 16-inch",
    "description": "Development laptop assigned to engineering team",
    "owner": "John Doe",
    "metadata": {
      "serialNumber": "C02XK1F2JGH7",
      "purchaseDate": "2025-01-15",
      "warranty": "3 years",
      "department": "Engineering"
    }
  }'

Request

HTTP Method

POST

URL

https://api.g2cplatform.com/v2/categories/{CATEGORY_ID}/subcategories/{SUBCATEGORY_ID}/objects

Path Parameters

Parameter	Type	Required	Description
`CATEGORY_ID`	string (UUID)	✅	Category identifier
`SUBCATEGORY_ID`	string (UUID)	✅	Subcategory identifier

Request Body

Field	Type	Required	Description
`externalId`	string	✅	External identifier (1-100 characters, unique within company)
`name`	string	✅	Object name (2-200 characters)
`description`	string	❌	Detailed description (max 1000 characters)
`summary`	string	❌	Brief summary (max 500 characters)
`owner`	string	❌	Current owner (max 100 characters)
`metadata`	object	❌	Additional metadata as key-value pairs

Headers

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Response

Success Response (201 Created)

{
  "id": "obj_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o",
  "externalId": "LAPTOP-001",
  "name": "MacBook Pro 16-inch",
  "description": "Development laptop assigned to engineering team",
  "summary": null,
  "owner": "John Doe",
  "status": "active",
  "categoryId": "cat_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "subcategoryId": "sub_2b3c4d5e-6f7g-8h9i-0j1k-2l3m4n5o6p7q",
  "metadata": {
    "serialNumber": "C02XK1F2JGH7",
    "purchaseDate": "2025-01-15",
    "warranty": "3 years",
    "department": "Engineering"
  },
  "createdAt": "2025-08-03T10:30:00Z",
  "updatedAt": "2025-08-03T10:30:00Z",
  "blockchain": {
    "txId": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567",
    "lastTxId": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567",
    "eventCount": 1
  }
}

Response Headers

The response includes a Location header with the URL of the created object:

Location: https://api.g2cplatform.com/v2/companies/{COMPANY_ID}/objects/obj_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o

Error Responses

400 Bad Request

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-08-03T10:30:00Z",
  "validationErrors": [
    {
      "field": "externalId",
      "message": "External ID is required",
      "code": "REQUIRED"
    },
    {
      "field": "name",
      "message": "Name must be between 2 and 200 characters",
      "code": "LENGTH_INVALID"
    }
  ]
}

404 Not Found

{
  "error": "Subcategory not found",
  "code": "SUBCATEGORY_NOT_FOUND",
  "timestamp": "2025-08-03T10:30:00Z"
}

409 Conflict

{
  "error": "External ID already exists",
  "code": "EXTERNAL_ID_EXISTS",
  "timestamp": "2025-08-03T10:30:00Z"
}

Implementation Examples

Basic Object Creation

async function createObject(companyId, categoryId, subcategoryId, objectData) {
  try {
    const response = await fetch(
      `https://api.g2cplatform.com/v2/categories/${categoryId}/subcategories/${subcategoryId}/objects`,
      {
        method: 'POST',
        headers: {
          'X-API-Key': process.env.G2C_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(objectData)
      }
    );

    if (response.ok) {
      const object = await response.json();
      console.log('✅ Object created successfully:', object.externalId);
      return object;
    } else {
      const error = await response.json();
      throw new Error(`Object creation failed: ${error.error}`);
    }
  } catch (error) {
    console.error('❌ Object creation error:', error.message);
    throw error;
  }
}

// Usage
const object = await createObject(
  'company-uuid',
  'category-uuid',
  'subcategory-uuid',
  {
    externalId: 'DESK-001',
    name: 'Standing Desk',
    description: 'Adjustable height standing desk for office use',
    owner: 'Office Manager',
    metadata: {
      location: 'Building A, Floor 2',
      purchasePrice: '599.99',
      vendor: 'Office Furniture Co'
    }
  }
);

Object with Validation

function validateObjectData(data) {
  const errors = [];

  if (!data.externalId || data.externalId.length < 1 || data.externalId.length > 100) {
    errors.push('External ID must be between 1 and 100 characters');
  }

  if (!data.name || data.name.length < 2 || data.name.length > 200) {
    errors.push('Name must be between 2 and 200 characters');
  }

  if (data.description && data.description.length > 1000) {
    errors.push('Description must not exceed 1000 characters');
  }

  if (data.summary && data.summary.length > 500) {
    errors.push('Summary must not exceed 500 characters');
  }

  if (data.owner && data.owner.length > 100) {
    errors.push('Owner must not exceed 100 characters');
  }

  if (errors.length > 0) {
    throw new Error(`Validation failed: ${errors.join(', ')}`);
  }
}

async function createValidatedObject(companyId, categoryId, subcategoryId, objectData) {
  // Validate data before sending
  validateObjectData(objectData);

  const response = await fetch(
    `https://api.g2cplatform.com/v2/categories/${categoryId}/subcategories/${subcategoryId}/objects`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.G2C_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(objectData)
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error}`);
  }

  return response.json();
}

Bulk Object Creation

async function createMultipleObjects(companyId, categoryId, subcategoryId, objectsData) {
  const results = [];

  for (const objectData of objectsData) {
    try {
      const object = await createObject(companyId, categoryId, subcategoryId, objectData);
      results.push({ success: true, object });

      // Add small delay to avoid rate limiting
      await new Promise(resolve => setTimeout(resolve, 100));
    } catch (error) {
      results.push({
        success: false,
        error: error.message,
        data: objectData
      });
    }
  }

  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);

  console.log(`✅ Created ${successful.length} objects`);
  if (failed.length > 0) {
    console.log(`❌ Failed to create ${failed.length} objects`);
  }

  return { successful, failed };
}

// Usage
const objectsData = [
  {
    externalId: 'MONITOR-001',
    name: '27" 4K Monitor',
    owner: 'John Doe',
    metadata: { serialNumber: 'MON123456' }
  },
  {
    externalId: 'KEYBOARD-001',
    name: 'Mechanical Keyboard',
    owner: 'John Doe',
    metadata: { type: 'Cherry MX Blue' }
  }
];

const results = await createMultipleObjects(
  'company-uuid',
  'category-uuid',
  'subcategory-uuid',
  objectsData
);

Asset Registration System

class AssetRegistrationSystem {
  constructor(companyId, apiKey) {
    this.companyId = companyId;
    this.apiKey = apiKey;
  }

  async registerAsset(categoryId, subcategoryId, assetData) {
    const objectData = {
      externalId: assetData.assetTag || `ASSET-${Date.now()}`,
      name: assetData.name,
      description: assetData.description,
      owner: assetData.assignedTo,
      metadata: {
        assetTag: assetData.assetTag,
        serialNumber: assetData.serialNumber,
        purchaseDate: assetData.purchaseDate,
        purchasePrice: assetData.purchasePrice,
        vendor: assetData.vendor,
        location: assetData.location,
        condition: assetData.condition || 'new',
        warrantyExpiry: assetData.warrantyExpiry
      }
    };

    try {
      const object = await this.createObject(categoryId, subcategoryId, objectData);

      // Log the registration event
      console.log(`🏷️  Asset registered: ${object.externalId} - ${object.name}`);
      console.log(`📍 Location: ${assetData.location}`);
      console.log(`👤 Assigned to: ${assetData.assignedTo}`);
      console.log(`🔗 Blockchain TX: ${object.blockchain.txId}`);

      return object;
    } catch (error) {
      console.error(`❌ Failed to register asset ${assetData.assetTag}:`, error.message);
      throw error;
    }
  }

  async createObject(categoryId, subcategoryId, objectData) {
    const response = await fetch(
      `https://api.g2cplatform.com/v2/categories/${categoryId}/subcategories/${subcategoryId}/objects`,
      {
        method: 'POST',
        headers: {
          'X-API-Key': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(objectData)
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error);
    }

    return response.json();
  }
}

// Usage
const assetSystem = new AssetRegistrationSystem('company-uuid', process.env.G2C_API_KEY);

const newAsset = await assetSystem.registerAsset(
  'category-uuid',
  'subcategory-uuid',
  {
    assetTag: 'LAPTOP-2025-001',
    name: 'Dell XPS 13',
    description: 'Ultrabook for mobile development team',
    assignedTo: 'Jane Smith',
    serialNumber: 'DXS13-987654321',
    purchaseDate: '2025-08-01',
    purchasePrice: '1299.99',
    vendor: 'Dell Technologies',
    location: 'Remote Work',
    warrantyExpiry: '2028-08-01'
  }
);

Use Cases

IT Asset Management

// Register a new computer
const computer = await createObject(companyId, itCategoryId, computersSubcategoryId, {
  externalId: 'COMP-2025-001',
  name: 'Development Workstation',
  description: 'High-performance workstation for software development',
  owner: 'Development Team',
  metadata: {
    cpu: 'Intel i9-13900K',
    ram: '32GB DDR5',
    storage: '1TB NVMe SSD',
    gpu: 'NVIDIA RTX 4080',
    operatingSystem: 'Windows 11 Pro',
    purchaseDate: '2025-08-01',
    warrantyExpiry: '2028-08-01'
  }
});

Vehicle Fleet Management

// Register a company vehicle
const vehicle = await createObject(companyId, vehiclesCategoryId, carsSubcategoryId, {
  externalId: 'VEH-001',
  name: 'Toyota Camry 2025',
  description: 'Company sedan for sales team',
  owner: 'Sales Department',
  metadata: {
    vin: '1HGBH41JXMN109186',
    licensePlate: 'ABC-123',
    year: '2025',
    make: 'Toyota',
    model: 'Camry',
    color: 'Silver',
    mileage: '0',
    insuranceExpiry: '2026-08-01',
    registrationExpiry: '2026-08-01'
  }
});

Equipment Tracking

// Register manufacturing equipment
const equipment = await createObject(companyId, equipmentCategoryId, machinerySubcategoryId, {
  externalId: 'EQ-LATHE-001',
  name: 'CNC Lathe Machine',
  description: 'Precision CNC lathe for metal fabrication',
  owner: 'Manufacturing Floor A',
  metadata: {
    manufacturer: 'Haas Automation',
    model: 'ST-10',
    serialNumber: 'ST10-123456',
    installationDate: '2025-08-01',
    lastMaintenance: '2025-08-01',
    nextMaintenance: '2025-11-01',
    operatingHours: '0',
    maxRPM: '4000'
  }
});

Best Practices

External ID Strategy

Use consistent naming patterns (e.g., ASSET-YYYY-NNN)
Include category or type in the ID for easy identification
Ensure IDs are human-readable and meaningful
Consider future scaling when designing ID patterns

Metadata Management

Store all relevant asset information in metadata
Use consistent field names across similar objects
Include purchase information for asset tracking
Add location and assignment data for inventory management

Error Handling

Always validate external ID uniqueness before creation
Handle network failures with retry logic
Log all creation attempts for audit purposes
Provide meaningful error messages to users

Performance

Create objects in batches with appropriate delays
Cache category and subcategory IDs to reduce lookups
Use bulk operations for large imports
Monitor blockchain transaction confirmations

Next Steps

Update Object

Learn how to update objects and track changes

Upload Files

Associate files and documents with your objects

List Objects

Query and filter your digital objects

Object Details

Retrieve detailed object information and history

Overview

System

Wallet Authentication

Wallet Management

Token Management

Category Management

Subcategory Management

Object Management

File Management

Endpoint

Request

HTTP Method

URL

Path Parameters

Request Body

Headers

Response

Success Response (201 Created)

Response Headers

Error Responses

400 Bad Request

404 Not Found

409 Conflict

Implementation Examples

Basic Object Creation

Object with Validation

Bulk Object Creation

Asset Registration System

Use Cases

IT Asset Management

Vehicle Fleet Management

Equipment Tracking

Best Practices

Next Steps

Update Object

Upload Files

List Objects

Object Details

Overview

System

Wallet Authentication

Wallet Management

Token Management

Category Management

Subcategory Management

Object Management

File Management

​Endpoint

​Request

​HTTP Method

​URL

​Path Parameters

​Request Body

​Headers

​Response

​Success Response (201 Created)

​Response Headers

​Error Responses

​400 Bad Request

​404 Not Found

​409 Conflict

​Implementation Examples

​Basic Object Creation

​Object with Validation

​Bulk Object Creation

​Asset Registration System

​Use Cases

​IT Asset Management

​Vehicle Fleet Management

​Equipment Tracking

​Best Practices

​Next Steps

Update Object

Upload Files

List Objects

Object Details

Endpoint

Request

HTTP Method

URL

Path Parameters

Request Body

Headers

Response

Success Response (201 Created)

Response Headers

Error Responses

400 Bad Request

404 Not Found

409 Conflict

Implementation Examples

Basic Object Creation

Object with Validation

Bulk Object Creation

Asset Registration System

Use Cases

IT Asset Management

Vehicle Fleet Management

Equipment Tracking

Best Practices

Next Steps