Records

Your products, fully structured

Records are your products. Each record belongs to a schema, stores dimension-scoped values, moves through lifecycle states, tracks completeness scores, and maintains a full audit trail of every change.

Scoped Values

Every value is stored with a scope object. An empty scope {} is global. A scope like {"dim-language": "seg-da"} targets Danish specifically.

Lifecycle States

Records move through states like Draft, Review, and Published. Transitions can require specific roles and minimum completeness scores.

Completeness Scoring

Track how complete each record is — which required attributes are filled, which are missing, and the overall percentage per lifecycle state.

Audit Trail

Every create, update, delete, and transition is logged with the user, timestamp, and exact attribute changes including old and new values.

Record Endpoints

List records

GET /api/v1/records

Returns a paginated list of records. Filter by schema or lifecycle state. Results include total count for pagination.

Parameter	In	Type	Description
`schemaId`	query	string	Filter by schema ID
`lifecycleStateId`	query	string	Filter by lifecycle state ID
`offset`	query	number	Pagination offset (default: `0`)
`limit`	query	number	Page size (default: `50`)

curl "https://api.sigma-pim.com/api/v1/records?schemaId=schema-apparel&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "items": [
    {
      "id": "ent-coastal-wb",
      "schemaId": "schema-apparel",
      "lifecycleStateId": "state-draft",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-16T14:22:00Z",
      "createdBy": "user-admin",
      "updatedBy": "user-admin",
      "values": {
        "product-name": [
          { "scope": {}, "value": "Coastal Windbreaker" },
          { "scope": { "dim-language": "seg-da" }, "value": "Kyst Vindjakke" }
        ],
        "sku": [
          { "scope": {}, "value": "CW-001" }
        ],
        "price": [
          { "scope": {}, "value": 129.99 },
          { "scope": { "dim-market": "seg-dk" }, "value": 969 }
        ]
      }
    }
  ],
  "total": 47,
  "offset": 0,
  "limit": 10
}

Create a record

POST /api/v1/records

Creates a new product record. The record is assigned to a schema and receives initial attribute values. Each value is an array of ScopedValue objects, allowing the same attribute to hold different values per dimension (e.g. different product names per language). The Early Access plan enforces a 500 SKU limit.

Field	Type	Required	Description
`schemaId`	string	Yes	Schema this record belongs to
`values`	Record<string, ScopedValue[]>	Yes	Attribute values keyed by attribute alias. Each value is an array of scoped values

ScopedValue shape:

Field	Type	Description
`scope`	object	Dimension scope map. Empty `{}` for global values. Keys are dimension IDs, values are segment IDs
`value`	any	The attribute value (type depends on the attribute's `dataType`)

curl -X POST https://api.sigma-pim.com/api/v1/records \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "schemaId": "schema-apparel",
    "values": {
      "product-name": [
        { "scope": {}, "value": "Coastal Windbreaker" },
        { "scope": {"dim-language": "seg-da"}, "value": "Kyst Vindjakke" },
        { "scope": {"dim-language": "seg-de"}, "value": "Kuesten Windjacke" }
      ],
      "sku": [
        { "scope": {}, "value": "CW-001" }
      ],
      "price": [
        { "scope": {}, "value": 129.99 },
        { "scope": {"dim-market": "seg-dk"}, "value": 969 }
      ],
      "description": [
        { "scope": {}, "value": "Lightweight windbreaker for coastal adventures" },
        { "scope": {"dim-language": "seg-da"}, "value": "Let vindjakke til eventyr langs kysten" }
      ]
    }
  }'

// Response — 201 Created
{
  "id": "ent-xK9mP2vL",
  "schemaId": "schema-apparel",
  "lifecycleStateId": "state-draft",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "createdBy": "user-admin",
  "updatedBy": "user-admin",
  "values": {
    "product-name": [
      { "scope": {}, "value": "Coastal Windbreaker" },
      { "scope": { "dim-language": "seg-da" }, "value": "Kyst Vindjakke" },
      { "scope": { "dim-language": "seg-de" }, "value": "Kuesten Windjacke" }
    ],
    "sku": [
      { "scope": {}, "value": "CW-001" }
    ],
    "price": [
      { "scope": {}, "value": 129.99 },
      { "scope": { "dim-market": "seg-dk" }, "value": 969 }
    ],
    "description": [
      { "scope": {}, "value": "Lightweight windbreaker for coastal adventures" },
      { "scope": { "dim-language": "seg-da" }, "value": "Let vindjakke til eventyr langs kysten" }
    ]
  }
}

Get a record

GET /api/v1/records/:id

Returns a single record by ID, including all scoped attribute values, lifecycle state, and timestamps.

Parameter	In	Description
`id`	path	Record ID (e.g. `ent-xK9mP2vL`)

curl https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "id": "ent-xK9mP2vL",
  "schemaId": "schema-apparel",
  "lifecycleStateId": "state-draft",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T14:22:00Z",
  "createdBy": "user-admin",
  "updatedBy": "user-admin",
  "values": {
    "product-name": [
      { "scope": {}, "value": "Coastal Windbreaker" },
      { "scope": { "dim-language": "seg-da" }, "value": "Kyst Vindjakke" }
    ],
    "sku": [{ "scope": {}, "value": "CW-001" }],
    "price": [{ "scope": {}, "value": 129.99 }]
  }
}

Update a record

PUT /api/v1/records/:id

Updates a record's attribute values. Provide the full values map — attributes included in the request body will replace their existing scoped values. Attributes not included remain unchanged. Values are validated against the attribute's data type and validation rules.

Parameter	In	Description
`id`	path	Record ID to update

Field	Type	Required	Description
`values`	Record<string, ScopedValue[]>	Yes	Updated attribute values

curl -X PUT https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "price": [
        { "scope": {}, "value": 149.99 },
        { "scope": {"dim-market": "seg-dk"}, "value": 1099 },
        { "scope": {"dim-market": "seg-de"}, "value": 159.99 }
      ]
    }
  }'

// Response
{
  "id": "ent-xK9mP2vL",
  "schemaId": "schema-apparel",
  "lifecycleStateId": "state-draft",
  "updatedAt": "2024-01-17T09:15:00Z",
  "updatedBy": "user-admin",
  "values": {
    "product-name": [
      { "scope": {}, "value": "Coastal Windbreaker" },
      { "scope": { "dim-language": "seg-da" }, "value": "Kyst Vindjakke" }
    ],
    "sku": [{ "scope": {}, "value": "CW-001" }],
    "price": [
      { "scope": {}, "value": 149.99 },
      { "scope": { "dim-market": "seg-dk" }, "value": 1099 },
      { "scope": { "dim-market": "seg-de" }, "value": 159.99 }
    ]
  }
}

Delete a record

DELETE /api/v1/records/:id

Permanently deletes a record and all its variants. This action is irreversible. The deletion is logged in the audit trail.

Parameter	In	Description
`id`	path	Record ID to delete

curl -X DELETE https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — 204 No Content

Update a single attribute

PATCH /api/v1/records/:id/values/:attr

Updates scoped values for a single attribute on a record. This is more granular than PUT — it replaces only the specified attribute's values without touching other attributes. The :attr parameter is the attribute alias.

Parameter	In	Description
`id`	path	Record ID
`attr`	path	Attribute alias (e.g. `product-name`)

Field	Type	Required	Description
`scopedValues`	ScopedValue[]	Yes	Array of scoped values for this attribute

curl -X PATCH https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL/values/product-name \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopedValues": [
      { "scope": {}, "value": "Coastal Windbreaker Pro" },
      { "scope": {"dim-language": "seg-da"}, "value": "Kyst Vindjakke Pro" },
      { "scope": {"dim-language": "seg-de"}, "value": "Kuesten Windjacke Pro" }
    ]
  }'

// Response
{
  "id": "ent-xK9mP2vL",
  "schemaId": "schema-apparel",
  "updatedAt": "2024-01-17T11:45:00Z",
  "values": {
    "product-name": [
      { "scope": {}, "value": "Coastal Windbreaker Pro" },
      { "scope": { "dim-language": "seg-da" }, "value": "Kyst Vindjakke Pro" },
      { "scope": { "dim-language": "seg-de" }, "value": "Kuesten Windjacke Pro" }
    ],
    /* ... other attributes unchanged */
  }
}

Completeness & Lifecycle

Get completeness score

GET /api/v1/records/:id/completeness

Calculates the completeness score for a record. The score is dimension-aware (considers each scope combination), lifecycle-state-aware (uses the state's required attributes), and guard-aware (only counts visible attributes). Returns the number of filled and total required fields, percentage, and a list of missing attributes with their scope.

Parameter	In	Description
`id`	path	Record ID

curl https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL/completeness \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "entityId": "ent-xK9mP2vL",
  "lifecycleStateId": "state-draft",
  "filled": 5,
  "total": 7,
  "percentage": 71,
  "missing": [
    { "attributeAlias": "description", "scope": { "dim-language": "seg-de" } },
    { "attributeAlias": "material", "scope": {} }
  ]
}

Execute lifecycle transition

POST /api/v1/records/:id/transition

Moves a record from one lifecycle state to another. The transition must be valid: it must exist in the workflow, the current user's role must be in the transition's allowedRoleIds, and if the transition requiresCompleteness, the record must be 100% complete for the target state. Returns an error if any gate fails.

Parameter	In	Description
`id`	path	Record ID

Field	Type	Required	Description
`transitionId`	string	Yes	ID of the transition to execute (from the workflow definition)

curl -X POST https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL/transition \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "transitionId": "trans-draft-to-review" }'

// Response
{
  "id": "ent-xK9mP2vL",
  "schemaId": "schema-apparel",
  "lifecycleStateId": "state-review",
  "updatedAt": "2024-01-18T08:00:00Z",
  "values": { /* ... */ }
}

Get available transitions

GET /api/v1/records/:id/transitions

Returns the list of transitions available from the record's current lifecycle state. Useful for building UI that shows which actions a user can take on a product.

Parameter	In	Description
`id`	path	Record ID

curl https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL/transitions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "id": "trans-review-to-published",
    "fromStateId": "state-review",
    "toStateId": "state-published",
    "name": "Publish",
    "allowedRoleIds": ["role-admin", "role-editor"],
    "requiresCompleteness": true
  },
  {
    "id": "trans-review-to-draft",
    "fromStateId": "state-review",
    "toStateId": "state-draft",
    "name": "Send back to draft",
    "allowedRoleIds": ["role-admin"],
    "requiresCompleteness": false
  }
]

Audit & Categories

Get audit history

GET /api/v1/records/:id/audit

Returns the audit trail for a record — every create, update, delete, and lifecycle transition. Each entry includes the user who made the change, a timestamp, the action type, and the specific attribute changes with old and new values.

Parameter	In	Type	Description
`id`	path	string	Record ID
`limit`	query	number	Max entries to return (default: `50`)

curl "https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL/audit?limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "id": "audit-7kP2mN",
    "entityId": "ent-xK9mP2vL",
    "userId": "user-admin",
    "timestamp": "2024-01-17T11:45:00Z",
    "action": "update",
    "changes": [
      {
        "attributeAlias": "product-name",
        "scope": {},
        "oldValue": "Coastal Windbreaker",
        "newValue": "Coastal Windbreaker Pro"
      }
    ]
  },
  {
    "id": "audit-3xR9vQ",
    "entityId": "ent-xK9mP2vL",
    "userId": "user-admin",
    "timestamp": "2024-01-18T08:00:00Z",
    "action": "transition",
    "changes": [
      {
        "attributeAlias": "lifecycleState",
        "scope": {},
        "oldValue": "state-draft",
        "newValue": "state-review"
      }
    ]
  }
]

Get category assignments

GET /api/v1/records/:id/categories

Returns all catalog categories that this record is assigned to. A record can belong to multiple categories across different catalogs.

Parameter	In	Description
`id`	path	Record ID

curl https://api.sigma-pim.com/api/v1/records/ent-xK9mP2vL/categories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "entityId": "ent-xK9mP2vL",
    "categoryId": "cat-outerwear",
    "sortOrder": 0
  },
  {
    "entityId": "ent-xK9mP2vL",
    "categoryId": "cat-spring-collection",
    "sortOrder": 3
  }
]

Understanding Scoped Values

Every attribute value in Sigma PIM is stored with a scope that determines which dimension context it applies to. This is the foundation of multi-language, multi-market, and multi-channel product data.

// Global value (no dimension scope)
{ "scope": {}, "value": "CW-001" }

// Danish language value
{ "scope": { "dim-language": "seg-da" }, "value": "Kyst Vindjakke" }

// German language value
{ "scope": { "dim-language": "seg-de" }, "value": "Kuesten Windjacke" }

// Danish market price
{ "scope": { "dim-market": "seg-dk" }, "value": 969 }

// Multi-dimension scope: Danish language + Danish market
{ "scope": { "dim-language": "seg-da", "dim-market": "seg-dk" }, "value": "Vindjakke til den danske kyst" }

An attribute's dimensionIds (defined in the schema) determines which dimensions it can be scoped to. A SKU with dimensionIds: [] only accepts the global scope. A product name with dimensionIds: ["dim-language"] can have different values per language segment.

Previous Schemas & Attributes Next Variants