--- title: "listUseCases" method: GET path: "/v1/integrations/{integrationId}/use-cases" tags: ["integrations"] --- # listUseCases `GET /v1/integrations/{integrationId}/use-cases` Retrieve all use cases for a specific integration ## Path parameters - `integrationId` string, uuid, required ## Response `200` Successfully retrieved use cases - object - `use_cases` UseCase[], required - union - InboundUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'inbound', required — Use case type - `enabled` boolean, required - `change_description` string — Description of the last change made to this use case - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` InboundIntegrationEventConfiguration — Configuration for inbound use cases (ERP to epilot) - `entities` IntegrationEntity[] — Array of entity configurations for this event - `entity_schema` string, required — Target entity schema (e.g., 'contact', 'contract') - `unique_ids` string[], required — Array of attribute names that uniquely identify this entity. The _type hint for repeatable fields (e.g., email, phone) should be specified on the corresponding field definition in the fields array. - `jsonataExpression` string — Optional JSONata expression to pre-process the event data before field mapping - `enabled` union — Controls whether this entity mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean. - … - `mode` 'upsert' | 'delete' | 'purge' | 'upsert-prune-scope-purge' | 'upsert-prune-scope-delete' — Operation mode for entity mapping: - 'upsert': Create or update the entity (default) - 'delete': Soft delete the entity (marks as deleted) - 'purge': Hard delete the entity (permanent removal) - 'upsert-prune-scope-purge': Upsert entities from array, then purge entities in scope that weren't upserted - 'upsert-prune-scope-delete': Upsert entities from array, then soft delete entities in scope that weren't upserted - `scope` PruneScopeConfig — Scope configuration for upsert-prune-scope modes. Defines how to find entities that should be pruned if not in the upsert payload. The scope is resolved against the original event payload (not individual array items). - … - `fields` IntegrationEntityField[], required — Field mapping definitions - … - `meter_readings` IntegrationMeterReading[] — Array of meter reading configurations for this event - `jsonataExpression` string — Optional JSONata expression to extract meter reading items from the event data. If not provided, the entire payload is used as the reading data. Useful when you need to extract an array of readings from a nested structure (e.g., "$.readings"). - `reading_matching` 'external_id' | 'strict-date' — Strategy for matching incoming readings against existing readings. - 'external_id': Match readings by external_id attribute (default behavior) - 'strict-date': Match by meter_id + counter_id + direction + date (German timezone). Useful when readings originate from ECP and are echoed back by the ERP with truncated timestamps. - `mode` 'upsert' | 'delete' | 'upsert-prune-scope' — Operation mode for meter reading mapping: - 'upsert': Create or update meter readings (default) - 'delete': Delete the meter reading - 'upsert-prune-scope': Upsert readings from array, then delete all other readings for the same meter+counter that weren't upserted - `scope` MeterReadingPruneScopeConfig — Scope configuration for meter reading upsert-prune-scope mode. The scope is all readings for the same meter + counter. - … - `meter` MeterUniqueIdsConfig, required - … - `meter_counter` MeterUniqueIdsConfig - … - `fields` IntegrationEntityField[], required — Field mapping definitions for meter reading attributes - … - OutboundUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'outbound', required — Use case type - `enabled` boolean, required - `change_description` string — Description of the last change made to this use case - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` OutboundIntegrationEventConfiguration — Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings. - `event_catalog_event` string, required — The Event Catalog event name that triggers this outbound flow - `mappings` OutboundMapping[], required — List of mappings that transform and deliver the event - `id` string, uuid — Unique identifier for this mapping - `name` string, required — Human-readable name for this mapping - `jsonata_expression` string — JSONata expression to transform the event payload. Required for webhook delivery; ignored for poll delivery. - `enabled` boolean, required — Whether this mapping is active - `delivery` union, required — Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload) - … - `created_at` string, date-time — Timestamp when the mapping was created - `updated_at` string, date-time — Timestamp when the mapping was last updated - FileProxyUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'file_proxy', required — Use case type - `enabled` boolean, required - `change_description` string — Description of the last change made to this use case - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` FileProxyUseCaseConfiguration — Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems. The file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters. The `orgId` is included in the signed URL to establish organization context without requiring authentication. Additional use-case-specific parameters are declared in the `params` array. - `secure_proxy` FileProxySecureProxyAttachment - `use_case_slug` string, required — Slug of the secure_proxy use case in the same integration. - `auth` FileProxyAuth - `type` 'oauth2_client_credentials' | 'oauth2_password', required — Authentication type - `token_url` string, required — Handlebars template for the OAuth2 token endpoint URL - `client_id` string, required — Handlebars template for the OAuth2 client ID - `client_secret` string, required — Handlebars template for the OAuth2 client secret - `scope` string — Optional OAuth2 scope - `audience` string — Handlebars template for the OAuth2 audience parameter - `resource` string — Handlebars template for the OAuth2 resource parameter - `username` string — Handlebars template for the OAuth2 resource owner username. Required when type is oauth2_password. - `password` string — Handlebars template for the OAuth2 resource owner password. Required when type is oauth2_password. - `body_params` object — Additional key-value pairs to include in the token request body. Values support Handlebars templates. - `headers` object — Additional headers to include in the token request. Values support Handlebars templates. - `query_params` object — Additional query parameters to append to the token URL. Values support Handlebars templates. - `params` FileProxyParam[] — Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, and useCaseSlug or useCaseId) - `name` string, required — Parameter name as it appears in the query string - `required` boolean, required — Whether this parameter is required - `description` string — Human-readable description of the parameter - `allowed_origins` string[] — Additional origins permitted to call /download for this use case (CORS, exact match). Portal origins are always allowed. - `steps` FileProxyStep[], required — Ordered list of HTTP steps to execute to retrieve the file - `url` string, required — Handlebars template for the request URL - `method` 'GET' | 'POST', required — HTTP method - `headers` object — Handlebars templates for request headers - `body` string — Handlebars template for the request body (POST only) - `response_type` 'json' | 'binary', required — Expected response type - `response` FileProxyResponseConfig, required - `body` string, required — JSONata expression to extract file content from step results - `encoding` 'base64' | 'binary', required — Encoding of the extracted body - `filename` string — JSONata expression to extract the filename - `content_type` string — JSONata expression to extract the content type - `prevent_indirect_serving` boolean — When `true`, this use case is served via the streaming endpoint: mapped file URLs are built as `/stream/download`, files of any size are streamed inline over HTTP response streaming, and buffered `/download` requests for oversize files are 307-redirected to `/stream`. Files never transit epilot's temporary S3 storage on the streaming path. Defaults to `false` (small files are served directly and large files are transparently served via a temporary S3 redirect). - ManagedCallUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'managed_call', required — Use case type for managed API calls - `enabled` boolean, required - `change_description` string — Description of the last change made to this use case - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` ManagedCallOperationConfig — Configuration for managed_call use cases. Defines a single API operation with JSONata mapping. - `operation` ManagedCallOperation, required — HTTP operation configuration for managed calls - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required - `path` string, required — URL path template with {{variable}} interpolation - `headers` object — Custom HTTP headers for the request. Values support {{variable}} interpolation from the request payload and {{env.VAR}} references for environment variables. - `query_params` object — Query parameters for the request. Values support {{variable}} interpolation from the request payload. - `request_mapping` string — JSONata expression for outbound body transformation - `response_mapping` string — JSONata expression for inbound response transformation - `inbound_use_case_slug` string — Slug of the inbound use case to route responses to for async entity processing. When set, the managed call response is queued to the inbound pipeline and processed using the referenced inbound use case's mapping configuration. - `type_annotations` TypeAnnotations — Developer-provided type annotations for a use case's request and response fields - `request` object — Type annotations for request fields, keyed by dot-path (e.g., "vendors[].id" -> "string") - `response` object — Type annotations for response fields - `types_locked` boolean — Whether types have been generated for this use case - SecureProxyUseCase - `id` string, uuid, required — Unique identifier for the use case - `integrationId` string, uuid, required — Parent integration ID - `name` string, required — Use case name - `slug` string — URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only. - `type` 'secure_proxy', required — Use case type - `enabled` boolean, required - `change_description` string — Description of the last change made to this use case - `created_at` string, date-time, required — ISO-8601 timestamp when the use case was created - `updated_at` string, date-time, required — ISO-8601 timestamp when the use case was last updated - `configuration` SecureProxyUseCaseConfiguration — Configuration for secure_proxy use cases. Defines how to route requests through a secure VPC. - `vpc_mode` 'static_ip' | 'secure_link', required — VPC routing mode. Read-only after creation. - static_ip: Routes through a VPC with static outbound IP (NAT Gateway) for IP-allowlisted external APIs. - secure_link: Routes through a VPN VPC for accessing private customer networks. - `allowed_domains` string[] — Domain whitelist for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script. Supports exact match (e.g., "api.wemag.com") and wildcard prefix (e.g., "*.wemag.com"). - `allowed_ips` string[] — IP allowlist (CIDR notation) for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script. Required for secure_link mode. All DNS-resolved IPs must match at least one range. Example: ["10.0.1.0/24", "192.168.1.0/24"] ## Other responses - `401` — Unauthorized request - `500` — Internal Server Error --- [API](https://skmtc.net/epilot/apis/integration-toolkit-api.md) · [All operations](https://skmtc.net/epilot/apis/integration-toolkit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/integration-toolkit-api/revisions/c24837d75096/schema)