Lookup Keys

The Propeller REST API provides multiple ways to identify and reference resources across the platform. These identification methods are called lookup keys and offer flexibility for different integration scenarios and data management workflows.

Overview

Lookup keys allow you to reference resources using various identifiers that make sense in your business context. For example, a product can be identified by its internal Propeller ID, its SKU, or its external system identifier. This flexibility is crucial for:

• System Integration: Mapping between external systems and Propeller
• Data Migration: Maintaining relationships during data imports
• Bulk Operations: Efficiently processing large datasets
• Business Logic: Using business-relevant identifiers

Available Lookup Keys

Lookup Key	Type	Description	Uniqueness	Use Cases
id	integer	Unique Propeller internal identifier	Always unique	Internal operations, direct references
sourceId	string	External system identifier	Unique when combined with source	System integrations, data imports
sku	string	Stock-keeping unit code	May not be unique	Product catalog management
supplierCode	string	Supplier's product code	May not be unique	Supplier relationships
externalId	string	Legacy external identifier	Always unique	Backward compatibility

Detailed Lookup Key Descriptions

ID Lookup Key

• Format: Integer (e.g., 481189)
• Uniqueness: Always unique within Propeller
• Usage: Primary identifier for internal operations
• Example: GET /v2/products/id/481189

SourceId/Source Combination

• Format: sourceId (string) + source (string)
• Uniqueness: Unique combination of both values
• Usage: Most common for system integrations
• Example: GET /v2/products/sourceId/NCABD70004

Lookup Key Usage Patterns

Single Resource Operations

For individual resource operations (GET, PATCH, DELETE), you can use any supported lookup key:

# Using internal ID
GET /v2/products/id/481189

# Using sourceId (with source parameter)
GET /v2/products/sourceId/NCABD70004

# Using SKU
GET /v2/products/sku/PROD-001

# Using supplierCode (with supplier parameter)
GET /v2/products/supplierCode/ABC123

Bulk Operations

Bulk endpoints require specific lookup key combinations:

# Bulk operations by sourceId
POST /v2/products/bulk/sourceId
{
  "products": [
    {
      "sourceId": "NCABD70004",
      "source": "TECHDATA",
      "names": [{"language": "EN", "value": "Product Name"}]
    }
  ]
}

Error Handling

When using lookup keys, be aware of potential error scenarios:

Multiple Resources Found

If a lookup key returns multiple resources, the API will return an error:

{
  "error": {
    "code": 80005,
    "status": 400,
    "type": "ProductMultipleFound",
    "messages": ["Multiple products found. Please provide additional filters"]
  }
}

Resource Not Found

When a resource doesn't exist with the specified lookup key:

{
  "error": {
    "code": 80006,
    "status": 404,
    "type": "ProductNotFound",
    "messages": ["Product with id [481189] not found"]
  }
}

Best Practices

System Integration

• Use sourceId/source for external system integrations
• Choose descriptive source names that reflect the origin system
• Ensure sourceId uniqueness within the source system

Bulk Operations

• Always use sourceId/source for bulk endpoints
• Include both parameters to ensure uniqueness
• Validate data before bulk operations

Product Management

• Use SKU for product catalog operations
• Implement SKU uniqueness validation in your systems
• Use supplierCode for supplier-specific operations

Error Prevention

• Always handle multiple resource scenarios
• Implement proper error handling for lookup failures
• Use additional filtering when lookup keys may not be unique

Resource-Specific Lookup Keys

Different resources support different lookup keys:

Resource	Supported Lookup Keys	Notes
Products	id, sourceId, sku, supplierCode	Most comprehensive support
Categories	id, sourceId	Hierarchical structure support
Companies	id, sourceId	B2B organizational structure
Customers	id, sourceId	B2C individual accounts
Contacts	id, sourceId	B2B user management
Clusters	id, sourceId	Product grouping
Cluster Config	id, name	Configuration management
Pricesheets	id, code	Pricing management
Attributes	id, name	Custom field management

Lookup keys provide the foundation for flexible resource identification across the Propeller platform, enabling seamless integration with external systems and efficient data management workflows.