> ## Documentation Index > Fetch the complete documentation index at: https://docs.cedarai.com/llms.txt > Use this file to discover all available pages before exploring further. # Classify a class list > Creates a class list (switch list) from a list of car numbers by automatically picking destination tracks based on the carrier's configured block-to-track scope. This is the API equivalent of the inventory **Classify** dialog: you provide just the cars, and Cedar mirrors the UI logic to compute where each car goes. Customers replacing the existing class-list API typically batch 5–60 cars per call, scoped to the lead/shift the crew is working — see the `switchListBatch` example for a realistic shape. Classification logic (per car, in request order): 1. Find the parent grouping of the carrier-configured block type (for example `yard_block`). 2. Look up the assigned tracks for that block in priority order. 3. Pick the first assigned track with capacity for the car. 4. Otherwise fall back to the lowest-priority assigned track. 5. Otherwise — only when a block exists — fall back to the car's current track if `classifyFallbackToCurrentTrack` is enabled in carrier settings. The operation is atomic: if any car cannot be resolved (missing in inventory, has no block of the carrier-configured type, or has no usable destination) the entire request is rejected and no class list is created. Cars without a block are always rejected, regardless of the fallback setting, mirroring the inventory dialog's behaviour. Usage notes: - `equipmentInitialAndNumbers` accepts entries like `"BNSF 999001"`. The order is preserved in the resulting class list (it determines `workOrderPriority` on the persisted tasks) and is also used for capacity accounting. - `scope` is optional. When omitted, the first scope accessible to the caller is used. Scopes that do not start with `block2track_` are automatically prefixed. A scope that is not configured for the carrier is rejected with `400 Bad Request`. - `jobId` is optional. Carriers commonly pass the train or job number the crew is working (for example `350` or `MORNING-JOB-12`); when omitted, a label like `Classify 2026-04-30 22:34:11 UTC` is generated. - `isBack` defaults to `false`; set to `true` to switch from the back of the track. - The inventory page also offers a **Classify by Current Track** action that splits a multi-track selection into one class list per source track. To replicate that, partition the cars by current track yourself and call this endpoint once per group (see the `byCurrentTrackPerCall` example). Permission required: `workOrderManagement.classList.classifyThirdParty`. ## OpenAPI ````yaml /user-docs/api-reference/external-openapi.json post /ims/work-orders/class-lists/classify openapi: 3.1.0 info: title: ARMS External API version: 1.0.0 description: >- OpenAPI specification generated from external API schemas. Endpoints require query parameter carrierId and headers x-arms-api-key and x-arms-assume-user. license: name: Proprietary url: https://cedarai.com servers: - url: https://api-lg.arms.cedarai.com description: Production (US) - url: https://api-lg.arms.cedarai.se description: Production (EU) security: - ApiKeyAuth: [] AssumeUser: [] paths: /ims/work-orders/class-lists/classify: post: summary: Classify a class list description: >- Creates a class list (switch list) from a list of car numbers by automatically picking destination tracks based on the carrier's configured block-to-track scope. This is the API equivalent of the inventory **Classify** dialog: you provide just the cars, and Cedar mirrors the UI logic to compute where each car goes. Customers replacing the existing class-list API typically batch 5–60 cars per call, scoped to the lead/shift the crew is working — see the `switchListBatch` example for a realistic shape. Classification logic (per car, in request order): 1. Find the parent grouping of the carrier-configured block type (for example `yard_block`). 2. Look up the assigned tracks for that block in priority order. 3. Pick the first assigned track with capacity for the car. 4. Otherwise fall back to the lowest-priority assigned track. 5. Otherwise — only when a block exists — fall back to the car's current track if `classifyFallbackToCurrentTrack` is enabled in carrier settings. The operation is atomic: if any car cannot be resolved (missing in inventory, has no block of the carrier-configured type, or has no usable destination) the entire request is rejected and no class list is created. Cars without a block are always rejected, regardless of the fallback setting, mirroring the inventory dialog's behaviour. Usage notes: - `equipmentInitialAndNumbers` accepts entries like `"BNSF 999001"`. The order is preserved in the resulting class list (it determines `workOrderPriority` on the persisted tasks) and is also used for capacity accounting. - `scope` is optional. When omitted, the first scope accessible to the caller is used. Scopes that do not start with `block2track_` are automatically prefixed. A scope that is not configured for the carrier is rejected with `400 Bad Request`. - `jobId` is optional. Carriers commonly pass the train or job number the crew is working (for example `350` or `MORNING-JOB-12`); when omitted, a label like `Classify 2026-04-30 22:34:11 UTC` is generated. - `isBack` defaults to `false`; set to `true` to switch from the back of the track. - The inventory page also offers a **Classify by Current Track** action that splits a multi-track selection into one class list per source track. To replicate that, partition the cars by current track yourself and call this endpoint once per group (see the `byCurrentTrackPerCall` example). Permission required: `workOrderManagement.classList.classifyThirdParty`. operationId: classifyClassList parameters: - $ref: '#/components/parameters/CarrierId' - $ref: '#/components/parameters/ViewAsUserGroup' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ClassifyClassListInput' examples: minimal: summary: Classify three cars using the carrier's default scope value: carrierId: 1234 equipmentInitialAndNumbers: - BNSF 999001 - UP 999010 - CSXT 999090 full: summary: Classify with an explicit scope, job label, and is-back flag value: carrierId: 1234 equipmentInitialAndNumbers: - BNSF 999001 - UP 999010 scope: shift1 jobId: MORNING-CLASSIFY-2026-04-30 isBack: true switchListBatch: summary: Typical morning switch list (mixed Class I and tank-car marks) description: >- A realistic batch the way a switch crew would build a class list: a dozen-plus cars sourced from one or two yard tracks, classified together under a job number that matches the train/job the crew is working. The numeric `jobId` mirrors how dispatchers actually label switch jobs in production. Equipment numbers in this example are synthetic placeholders (UMLER caps reporting marks at 6 digits). value: carrierId: 1234 scope: yard1_first_shift jobId: '350' equipmentInitialAndNumbers: - UTLX 999020 - UTLX 999021 - TILX 999030 - GATX 999040 - NATX 999050 - BNSF 999002 - DOWX 999060 - SHPX 999070 - GATX 999041 - PROX 999080 - UTLX 999022 - TILX 999031 byCurrentTrackPerCall: summary: >- One classify call per source track (mirrors the inventory dialog's 'Classify by Current Track') description: >- The inventory UI's 'Classify by Current Track' action partitions a multi-track selection by each car's current track and opens one dialog per group. To replicate that workflow over the API, group the cars yourself and call this endpoint once per source track. Each call produces an independent class list with its own job label so each switch crew gets a clean assignment list. value: carrierId: 1234 scope: yard1_first_shift jobId: 350-from-trk-A12 equipmentInitialAndNumbers: - UTLX 999020 - UTLX 999021 - TILX 999030 explicitScopeMultiShift: summary: >- Explicit shift-scoped classify (carriers often configure separate scopes per shift) description: >- Carriers commonly configure two or more block-to-track scopes per crew lead — for example a 1st-shift scope and a 2nd-shift scope that route the same yard blocks to different destination tracks. Pass the relevant scope explicitly to honour the right routing for the crew that is actually on duty. value: carrierId: 1234 scope: mainyard_lead_second_shift jobId: '352' equipmentInitialAndNumbers: - BNSF 999002 - BNSF 999003 - UP 999011 - UP 999012 - GATX 999040 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ClassList' '400': description: Bad Request '401': description: Unauthorized '404': description: Not Found '500': description: Internal Server Error default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: CarrierId: name: carrierId in: query required: true schema: type: integer description: Carrier identifier; required for all endpoints ViewAsUserGroup: name: viewAsUserGroup in: query required: false schema: type: string description: Optional user group context schemas: ClassifyClassListInput: type: object description: >- Input for classifying a class list (switch list) from a list of car numbers. properties: carrierId: type: integer description: Carrier identifier. equipmentInitialAndNumbers: type: array minItems: 1 description: >- Equipment initial and numbers to classify, e.g. ['BNSF 999001', 'UP 999010']. Order is preserved in the resulting class list and is also used for capacity accounting. items: type: string scope: type: string description: >- Block-to-track scope to use. Real-world scopes are usually named after the lead and shift the crew is working (for example `yard1_first_shift` or `mainyard_lead_morning`). If omitted, the first scope accessible to the caller is used. Values that do not start with `block2track_` are automatically prefixed (so `yard1_first_shift` and `block2track_yard1_first_shift` are equivalent). A scope that is not configured for the carrier is rejected with `400 Bad Request`. jobId: type: string description: >- User-specified label for the class list. Carriers commonly pass the train or job number the crew is working (for example `350` or `MORNING-JOB-12`). If omitted, a label like `Classify ` is generated. isBack: type: boolean description: True if switching from the back of the track. Defaults to false. default: false required: - carrierId - equipmentInitialAndNumbers ClassList: type: object description: >- A class list (switch list) represents a work order for switching operations. properties: resourceId: type: integer uuid: type: string description: UUID that complements the legacy numeric resourceId. jobId: type: string description: User-specified label for the class list status: type: string enum: - ACTIVE - ARCHIVED description: Status of the class list createdAt: type: string format: date-time description: When the class list was created cuts: type: array items: type: integer description: Cut positions in the class list isBack: type: boolean description: True if switching from the back of the track carrier: $ref: '#/components/schemas/CarrierResource' createdBy: $ref: '#/components/schemas/UserResource' Error: type: object properties: message: type: string CarrierResource: type: object properties: resourceType: type: string enum: - Carrier resourceId: type: integer uuid: type: string description: UUID that complements the legacy numeric resourceId. carrierCode: type: string name: type: string UserResource: type: object properties: resourceType: type: string enum: - User resourceId: type: integer uuid: type: string description: UUID that complements the legacy numeric resourceId. displayName: type: string email: type: string format: email securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-arms-api-key description: Your ARMS API key AssumeUser: type: apiKey in: header name: x-arms-assume-user description: Email of a user assigned to the appropriate user group ````