> ## Documentation Index > Fetch the complete documentation index at: https://documentation.claruswms.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an import configuration > Create a configuration describing how to parse and transform an external import file. ## Request Structure ```json expandable { "data": { "type": "import_configurations", "attributes": { "name": "Acme Orders CSV", "parser": "csv", "failure_strategy": "skip_resource", "settings": [ { "setting_type": "delimiter", "value": "," } ], "automatic_processing_flows": [ { "code": "process_line", "name": "Process Line", "processing_actions": [ { "action": "find_resource", "configuration": { "resource_name": "account", "resource_attribute": "code", "index": "AccountCode" } } ] } ] } } } ``` ## Key Fields | Field | Required | Description | | ---------------------------- | -------- | ------------------------------------------------ | | `name` | Yes | Configuration name | | `parser` | Yes | xml, headless\_csv, csv, edi, txt | | `failure_strategy` | Yes | skip\_resource or abort | | `settings` | No | Parser settings (e.g. delimiter, EDI separators) | | `pre_processors` | No | Steps applied before parsing | | `automatic_processing_flows` | Yes | Flows run automatically per record/row | | `manual_processing_flows` | No | Reusable flows invoked by other flows | ## Processing Model Files are parsed, optionally pre-processed, then transformed by processing flows. Each flow contains ordered `processing_actions` (e.g. `find_resource`, `build_resource`, `build_nested_resource`) whose `configuration` is action-specific. See the importing module docs for full action configuration details. ## OpenAPI ````yaml /api-reference/clarus-api.json post /api/import_configurations openapi: 3.0.3 info: title: ClarusWMS API description: >- REST and GraphQL API for ClarusWMS - a multi-tenanted SaaS warehouse management system. This API provides REST mutation endpoints (POST, PATCH, DELETE) for managing warehouse operations and GraphQL list endpoints for data retrieval. **REST mutations** are available at `/api/*` paths. **GraphQL queries** are available at `/graphql` — each resource has a documented list query. ## Authentication All endpoints require OAuth 2.0 Bearer token authentication. Use the client credentials or authorization code flow to obtain an access token from `https://clarus-api.com/oauth/token`. ## Multi-Tenancy This is a multi-tenant system. Each tenant (subdomain) has isolated data. **You must include the `X-Clarus-Subdomain` header with every request** to specify which tenant you are operating on. ### Required Header | Header | Required | Description | |--------|----------|-------------| | `X-Clarus-Subdomain` | Yes | The subdomain/tenant name identifying which tenant's data to access | **Example:** ``` X-Clarus-Subdomain: acme-warehouse ``` ## Request Format (JSON:API) All REST mutation requests use JSON:API format. Data must be sent within a `data` object containing `type` and `attributes`: ```json { "data": { "type": "resource_name", "attributes": { "field1": "value1" } } } ``` ## GraphQL Queries All data retrieval uses GraphQL at `POST /graphql`. Send a JSON body with `query` and optional `variables`: ```json { "query": "query($code: String) { accounts { all(code: $code) { edges { node { id code name } } } } }", "variables": { "code": "ACME" } } ``` version: 1.0.0 contact: name: Clarus Software url: https://claruswms.com servers: - url: https://clarus-api.com description: Production API security: - BearerAuth: [] ClarusSubdomain: [] tags: - name: Account Warehouses description: >- Account-warehouse association endpoints for managing which accounts can operate in which warehouses - name: Accounts description: Account/customer management endpoints for 3PL client management - name: Addresses description: >- Generic address management endpoints. Town/city is held in `address_3` (passed to couriers as the city). - name: Alternative Code Types description: Alternative code type reference endpoints categorising alternative codes. - name: Alternative Codes description: >- Alternative code management endpoints — additional identifiers (e.g. customer SKUs) attached to products, suppliers, carriers, or warehouses. - name: Automations description: >- Event-driven automation rules that trigger destination actions (API, FTP, email, webhook, file import, AI) when warehouse resource events fire, gated by configurable conditions. - name: Barcode Formats description: Barcode format reference endpoints. - name: Bookings description: >- Booking diary management endpoints for scheduling inbound and outbound dock appointments - name: Carriers description: >- Shipping carrier management endpoints (e.g. DHL, DPD, Royal Mail) used on shipments and goods out orders. - name: 'Carriers: Services' description: >- Carrier service-level endpoints (e.g. Next Day, Express) belonging to a carrier. - name: 'Charging: Baskets' description: >- Charge basket endpoints for collecting and invoicing billable charges against accounts. Each account has one open basket at a time that accumulates charge lines from warehouse operations. Use these endpoints to manage basket lifecycle and generate invoices. - name: 'Charging: Configuration' description: >- Charge configuration endpoints for managing charge cards, charge prices, and charge windows. Charge cards define billing profiles assigned to accounts. Charge prices define pricing rules within a card. Charge windows define recurring billing schedules. - name: 'Charging: Lines' description: >- Charge line management endpoints for individual billable line items within charge baskets. Charge lines are typically created automatically by warehouse operations but can also be created and managed manually. - name: Collection Addresses description: >- Collection address management endpoints. Collection addresses belong to a supplier and are used for inbound collections. - name: Crossdocks description: >- External crossdock management endpoints for direct inbound-to-outbound transfer. - name: Currencies description: Currency management endpoints. Codes are ISO 4217 in lowercase. - name: Custom Carrier Types description: >- Custom carrier type management endpoints, including print layout parameters for label/document templates. - name: Customers description: >- Customer management endpoints. Customers are the end-recipients of goods (distinct from stock accounts). - name: Dashboard Widgets description: >- Dashboard widget management endpoints for creating, updating, and deleting widgets. Each widget is bound to a report query and rendered on dashboards as a configurable chart (bar, line, pie, gauge, etc.). Widgets are placed onto dashboards via the dashboard's widget placement endpoint. - name: Dashboards description: >- Dashboard management endpoints for creating, updating, and deleting dashboards together with the widgets placed on them. Dashboards are role-scoped collections of widgets that render report query data as charts. Use the placement endpoint to atomically replace the widgets shown on a dashboard. - name: Delivery Addresses description: >- Delivery address management endpoints. Delivery addresses belong to an end customer and are used for outbound deliveries. - name: Documents description: >- Document management endpoints for downloading, uploading, and transferring generated files - name: External Entities description: >- External entity endpoints — references to items in external systems (e.g. Shopify products, carriers, shipping rates, warehouses) that are linked to internal ClarusWMS entities via mappings. - name: 'Goods In: Receipts' description: >- Inbound receipt management endpoints for receiving inventory into the warehouse, including the receive task actions used to confirm stock has been received against a receipt - name: 'Goods Out: Orders' description: >- Outbound order management endpoints for creating, updating, and cancelling sales orders - name: 'Goods Out: Pick Lists' description: Pick list management endpoints for updating and removing pick lists - name: 'Goods Out: Processing' description: >- Pick processing endpoints for generating pick lists and order fulfillment workflows - name: Groups description: Group management endpoints for organizing products and locations - name: HHD Flows description: >- Handheld device (HHD) flow definitions — configurable RF/HHD workflows belonging to an HHD implementation. Known internally as RF flows. - name: HHD Users description: >- RF (handheld device) user query endpoints. RF users are dedicated warehouse device operators. - name: Import Configurations description: >- Import configuration endpoints for ingesting external files (CSV, XML, EDI, TXT) and transforming them into warehouse resources via configurable processing flows. - name: Import Templates description: >- Import template management endpoints. Templates map inbound files (matched by filename regexp) onto warehouse resources for an SFTP user. - name: Integrations description: >- Third-party integration management endpoints for ecommerce, carrier, and ERP connections - name: Load Drops description: >- Load drop management endpoints — the individual delivery/collection stops on a load, including stop re-sequencing. - name: Loads description: Load management endpoints for grouping shipments onto vehicles - name: Location Types description: Location type management endpoints for classifying warehouse locations. - name: Locations description: Location management endpoints for warehouse storage locations - name: Mapping Groups description: >- Mapping group endpoints — containers that link external entities to internal entities for a given operation type, plus their field definitions. - name: Mappings description: >- Mapping endpoints — link external entities to internal records within a mapping group. Includes the generic mappings endpoint (for non-integration operation types) and the dedicated endpoints for integration carrier, shipping rate, warehouse, product, and FTP mappings. - name: Order Types description: Order type reference endpoints. - name: Packages description: >- Package endpoints — parcels within a shipment, with dimensions and tracking. - name: Printers description: Cloud Print printer management endpoints for document and label printing. - name: Products description: >- Product management endpoints for creating, updating, and deleting products in the warehouse catalog. ## GraphQL Filtering Guide Products support individual code/barcode filters: `code`, `barcode`, `case_barcode`, `inner_barcode`, `outer_barcode`. Each supports operators: `eq`, `ilike`, `in`, `like`, `between`. When multiple individual filters are used together, they are AND'd (all conditions must match). ### The `all_codes` filter `all_codes` is a **specialized cross-field search** that ORs across all 5 code fields (`code`, `barcode`, `case_barcode`, `inner_barcode`, `outer_barcode`) in a single query. It performs exact matching (IN operator), not partial/ILIKE matching. **When to use `all_codes`:** Only when you have a code or barcode value and don't know which field it belongs to — e.g., a user scans a barcode that could be a unit barcode, case barcode, inner barcode, or outer barcode. **When NOT to use `all_codes`:** When you know which specific code field to search. Use the individual filter instead for better performance and precision. - name: 'Products: Accounts' description: Assignments linking products to stock accounts. - name: 'Products: Materials' description: Bill-of-materials component lines for a parent product. - name: 'Products: Storage Units' description: >- Product storage unit configuration — how a product is packed into storage unit types (per-layer, layers, totals). - name: Putaway Rules description: Per-account putaway ordering rules, with re-sequencing. - name: Reason Codes description: >- Reason code endpoints for stock adjustments, holds, transfers, and stock checks. - name: Replenishment description: Replenishment endpoints for restocking pick faces from bulk storage - name: Report Queries description: Report query management endpoints for custom reporting and data extraction - name: Reports description: >- Report management endpoints for creating report definitions, updating configurations, and generating report output as downloadable documents - name: Roles description: Role and permission management endpoints for access control - name: Scheduled Reports description: >- Scheduled report management endpoints for recurring report delivery via email and FTP - name: SFTP Users description: >- FTP/SFTP user management endpoints for inbound (upload) and outbound (download) file transfer. - name: Shipments description: Shipment management endpoints for carrier integration and parcel tracking - name: Sites description: >- Site management endpoints. Sites group warehouses for multi-site operations. - name: Stock Balances description: >- Aggregated stock balance query endpoints summarising available, allocated, ordered, received, and picked quantities per product/account/warehouse. - name: Stock Checks description: >- Stock check endpoints for counting the products held at a location and reconciling them against the system. A stock check moves through `pending` to either `passed` or `failed`, and failed checks can subsequently be `resolved` with a reason code. - name: Stock Unit Types description: >- Stock unit type reference endpoints (the unit a product's stock is measured in). - name: Stocks description: >- Stock management endpoints for inventory operations including holds, moves, transfers, and adjustments - name: Storage Unit Types description: >- Storage unit type endpoints (pallets, cages, totes) with dimensions and barcode settings. - name: Storage Units description: >- Storage unit management endpoints for containers like pallets, cages, and boxes - name: Subdomains description: >- Tenant (subdomain) management endpoints. Creating a subdomain provisions a new tenant with its own isolated data; the subdomain slug cannot be changed once created. - name: Suppliers description: Supplier management endpoints. Suppliers are the source of inbound goods. - name: Tasks description: >- Task management endpoints for warehouse operations including picking, putaway, receiving, dispatch, and replenishment tasks. Tasks are created automatically by warehouse operations (e.g., goods in receipts, goods out orders, replenishment) and cannot be created or deleted via the API. Use these endpoints to update task attributes, manage task allocation to users, and complete tasks. - name: Tax Rates description: Tax rate management endpoints with percentage component rates. - name: Tax Types description: Tax type management endpoints. - name: Templates description: >- Template management endpoints for creating, updating, and testing Liquid HTML print templates - name: Trailer Types description: Trailer type reference endpoints. - name: Trailers description: Trailer management endpoints for loading and dispatch. - name: Transactions description: >- Read-only stock transaction history query endpoints. Transactions record every stock movement and cannot be created or modified via the API. - name: Users description: User management endpoints for system access and permissions - name: Warehouse Routes description: Per-product warehouse routing priorities, with re-sequencing. - name: Warehouses description: Warehouse management endpoints for multi-site operations paths: /api/import_configurations: post: tags: - Import Configurations summary: Create an import configuration description: >- Create a configuration describing how to parse and transform an external import file. operationId: createImportConfiguration requestBody: required: true content: application/json: schema: type: object required: - data properties: data: type: object required: - type - attributes properties: type: type: string enum: - import_configurations description: Resource type identifier attributes: $ref: '#/components/schemas/ImportConfigurationAttributes' responses: '200': description: Import configuration created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: integer description: Import configuration ID type: type: string enum: - import_configurations description: Resource type attributes: $ref: >- #/components/schemas/ImportConfigurationResponseAttributes '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: ImportConfigurationAttributes: type: object description: >- Import configuration attributes. Defines how an external file (CSV/XML/EDI/TXT) is parsed and transformed into warehouse resources. required: - name - parser - failure_strategy - automatic_processing_flows properties: name: type: string description: Display name of the import configuration. parser: type: string enum: - xml - headless_csv - csv - edi - txt description: File format parser. failure_strategy: type: string enum: - skip_resource - abort description: >- What to do when a resource fails: skip and continue, or abort the import. settings: type: array description: Parser settings. items: $ref: '#/components/schemas/ImportSetting' pre_processors: type: array description: Pre-processing steps applied before parsing. items: $ref: '#/components/schemas/ImportPreProcessor' automatic_processing_flows: type: array description: Flows that run automatically on each record/row. items: $ref: '#/components/schemas/ImportProcessingFlow' manual_processing_flows: type: array description: Reusable flows invoked by other flows (e.g. for nested lines). items: $ref: '#/components/schemas/ImportProcessingFlow' example: name: Acme Orders CSV parser: csv failure_strategy: skip_resource settings: - setting_type: delimiter value: ',' pre_processors: [] automatic_processing_flows: - code: process_line name: Process Line processing_actions: - action: find_resource configuration: resource_name: account resource_attribute: code index: AccountCode manual_processing_flows: [] ImportConfigurationResponseAttributes: type: object description: >- Import configuration attributes returned in responses. The parsed configuration is returned in the `configuration` object. properties: name: type: string description: Display name. parser: type: string enum: - xml - headless_csv - csv - edi - txt description: File format parser. failure_strategy: type: string enum: - skip_resource - abort description: Failure strategy. configuration: type: object additionalProperties: true description: >- Stored configuration (pre_processors, settings, automatic_processing_flows, manual_processing_flows). version: type: integer description: Configuration version. example: name: Acme Orders CSV parser: csv failure_strategy: skip_resource configuration: settings: [] pre_processors: [] automatic_processing_flows: [] manual_processing_flows: [] version: 1 ImportSetting: type: object description: A parser setting (e.g. CSV delimiter or EDI separators). required: - setting_type - value properties: setting_type: type: string enum: - delimiter - data_element_separator - sub_element_separator - escape_operator description: The setting being configured. value: type: string description: The setting value (e.g. ',' for a delimiter). example: setting_type: delimiter value: ',' ImportPreProcessor: type: object description: A pre-processing step applied to the raw file before parsing. required: - action - configuration properties: action: type: string enum: - remove_lines - remove_all_characters - dig - replace_all_characters - prefix_all_lines - suffix_all_lines description: The pre-processing action. configuration: type: object additionalProperties: true description: >- Action-specific configuration (e.g. { "path": "root.GoodsOut" } for dig). sequence: type: integer nullable: true description: Execution order. example: action: dig configuration: path: root.GoodsOut sequence: 1 ImportProcessingFlow: type: object description: A workflow that transforms file data into warehouse resources. required: - code - name - processing_actions properties: code: type: string description: Unique flow code. name: type: string description: Display name. sequence: type: integer nullable: true description: Execution order. conditions: type: object additionalProperties: true nullable: true description: >- Optional conditions controlling when the flow runs (e.g. { "start_with": "..." }). processing_actions: type: array description: Ordered transformation steps. items: $ref: '#/components/schemas/ImportProcessingAction' example: code: process_order name: Process Order sequence: 1 conditions: {} processing_actions: - action: find_resource configuration: resource_name: account resource_attribute: code index: AccountCode ErrorResponse: type: object description: Standard error response wrapper properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Array of error objects required: - errors ImportProcessingAction: type: object description: A single transformation step within a processing flow. required: - action - configuration properties: action: type: string enum: - find_resource - build_resource - build_nested_resource - execute_flow_on_each - find_nested_resource - set_artifact - set_metadata - set_resource_attribute - evaluate_conditionally - execute_actions_on_each description: The processing action. configuration: type: object additionalProperties: true description: >- Action-specific configuration (resource_name, attributes, data sources, etc.). sequence: type: integer nullable: true description: Execution order within the flow. example: action: find_resource configuration: resource_name: account resource_attribute: code index: AccountCode sequence: 1 Error: type: object description: Detailed error information properties: code: type: integer description: Numeric error code for programmatic handling symbol: type: string description: Symbolic error identifier (e.g., 'product_code_exists') details: type: string description: Human-readable error message source: type: string nullable: true description: Source of the error (service and method name) context: type: object nullable: true additionalProperties: true description: Additional context about the error required: - code - symbol - details responses: Unauthorized: description: Authentication required - provide a valid Bearer token content: application/json: schema: type: object properties: error: type: string description: Error message explaining authentication failure UnprocessableEntity: description: Validation error or business logic error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: oauth2 description: >- OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token. flows: clientCredentials: tokenUrl: https://clarus-api.com/oauth/token scopes: {} authorizationCode: authorizationUrl: https://clarus-api.com/oauth/authorize tokenUrl: https://clarus-api.com/oauth/token scopes: {} ClarusSubdomain: type: apiKey in: header name: X-Clarus-Subdomain description: >- The subdomain/tenant name identifying which tenant's data to access. Required for all API requests. ````