> ## Documentation Index > Fetch the complete documentation index at: https://docs.deck.co/llms.txt > Use this file to discover all available pages before exploring further. # Migrating from Sustainability > Moving from the legacy Sustainability, Bill, or Credit Risk APIs to Deck v2. The Deck Sustainability platform (including Bill and Credit Risk products) was a previous generation of the Deck platform with a fundamentally different architecture. v2 is a complete replacement. If you are on the legacy platform, this guide covers what you need to know. ## New account required The legacy Sustainability platform and Deck v2 are separate systems. You will need a new Deck account to use v2. * Data does not transfer. Credentials, statements, and historical data from the legacy platform are not accessible in v2. * API keys are not compatible. Legacy API credentials do not work with v2. * Create a new account at [console.deck.co](https://console.deck.co) and generate a v2 API key (`sk_live_`). Your legacy account continues to function while you migrate. ## Architecture differences The legacy platform was built around pre-defined data products (Sustainability, Bill, Credit Risk) with Deck-managed schemas. v2 is a general-purpose platform where you define your own agents, tasks, and schemas. | | Legacy (Sustainability) | Deck v2 | | -------------- | ------------------------------------------------------- | ------------------------------------------------------------------- | | Model | Pre-built data products with fixed endpoints | General-purpose agents with custom tasks | | Auth method | `client_id` + `secret` headers | `Authorization: Bearer sk_live_...` | | Base URL | `https://api.deck.co/` | `https://api.deck.co/v2` | | User linking | Deck Link (drop-in UI or API) | `POST /v2/credentials` with direct credential passing | | Token model | `link_token` → `public_token` → `access_token` exchange | Single `credential_id` returned directly | | Data retrieval | Call product-specific endpoints with `access_token` | Run tasks against credentials, receive structured output via events | | MFA | Dedicated security question and MFA endpoints | General-purpose interaction system | | Output format | Fixed response schemas per product | Custom output schemas defined per task | | Webhooks | Single endpoint, limited event types | Multiple destinations, granular event types, delivery tracking | | File access | Product-specific file download endpoints | Storage items with download URLs and optional data extraction | ## Concept mapping | Legacy Concept | v2 Concept | Notes | | ----------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Data product (Sustainability, Bill, Credit Risk) | Agent | Create one agent per use case. You define what it does. | | Source (utility provider, bank, etc.) | Source | On the legacy platform, sources were pre-configured by Deck and selected from a catalog. In v2, you create your own sources by providing a URL. You can connect to any website. | | Link session | Credential | Instead of a multi-step token exchange flow, create a credential directly with credentials in one API call. | | `link_token` | (not needed) | v2 does not use a token initialization step. | | `public_token` | (not needed) | v2 does not use a public/private token exchange. | | `access_token` | Credential ID (`cred_`) | The credential object is the handle for all subsequent operations. | | Product endpoint (e.g., `/sustainability/statements`) | Task Run | Define tasks for the data you need. Run them against credentials. Results come back as typed JSON. | | Statement file download | Storage item | Tasks can produce files. Download them via storage item URLs. | | Security question endpoint | Interaction | v2 handles all mid-flow prompts (MFA, security questions, account selection) through one interaction system. | | Auto-refresh | Credential scheduling | v2 supports scheduling on credentials for recurring data retrieval. | ## Source changes On the legacy platform, sources were pre-configured and managed by Deck. You connected to utility providers, banks, and other institutions from a fixed catalog. You could not add sources yourself. In v2, you create sources directly. Provide a name, type, and URL, and Deck handles the rest: ```json theme={null} POST /v2/sources { "name": "ConEd", "type": "website", "website": { "url": "https://coned.com" } } ``` This gives you access to any source, rather than being limited to ones predefined by Deck. If you were connecting to a utility provider or financial institution on the legacy platform, recreate it in v2 with the provider's login URL. Sources belong to your organization and can be shared across multiple agents. A single source can be used by both a sustainability agent and a bill pay agent. ## Authentication changes The legacy platform used a multi-step Link flow to establish credentials: ```text theme={null} 1. Create link_token → 2. User authenticates via Link UI → 3. Receive public_token → 4. Exchange for access_token ``` v2 replaces this entire flow with a single API call: ```bash theme={null} POST /v2/credentials { "source_id": "src_...", "auth_method": "username_password", "auth_credentials": { "username": "user@example.com", "password": "..." } } ``` The response gives you a `credential_id` immediately. If MFA is required, the credential status becomes `interaction_required` and you submit the code through the interaction endpoint. ## Data retrieval changes The legacy platform had fixed endpoints for each data product. You called an endpoint and received data in a predefined format. ### Legacy pattern ```bash theme={null} # Get all sustainability statements POST /sustainability/statements { "access_token": "..." } # Get a specific statement file POST /sustainability/statements/file { "access_token": "...", "statement_id": "..." } ``` ### v2 pattern ```bash theme={null} # Run a data retrieval task POST /v2/tasks/{task_id}/run { "credential_id": "cred_...", "input": { "date_range": "2025-01" } } # Results delivered via event: task_run.completed # Files available as storage items: GET /v2/task-runs/{run_id}/storage ``` In v2, you define what data to fetch through task definitions with custom input and output schemas. This gives you full control over the data structure instead of working within fixed product schemas. ## What v2 gives you Capabilities in v2 that did not exist on the legacy platform: * **Custom agents and tasks.** Define exactly what data to fetch and what actions to perform. Not limited to pre-built products. * **Any website as a source.** Create your own sources by URL. Not limited to the pre-configured catalog from the legacy platform. * **Typed schemas.** Define input and output schemas per task. Deck validates both ends. * **Interaction system.** Handle MFA, security questions, and account selection through a single, consistent API. * **Multiple event destinations.** Deliver events to webhooks, AWS SQS, GCP Pub/Sub, Azure Service Bus, and more. Subscribe each destination to specific event types. * **Idempotency.** All create endpoints accept idempotency keys for safe retries. * **Prefixed resource IDs.** Every ID encodes its type (`agt_`, `cred_`, `trun_`). ## Migration checklist Sign up at [console.deck.co](https://console.deck.co). Legacy accounts cannot be upgraded. Get your `sk_live_` API key from the Console. Map your legacy data products to agents. A Sustainability integration becomes an agent with tasks for fetching statements, downloading files, etc. Add the websites you were previously connecting to as sources. Provide the URL and Deck handles the rest. Create tasks that replicate the data you were fetching from legacy endpoints. Define input and output schemas that match your application's needs. Replace the `link_token` / `public_token` / `access_token` exchange flow with `POST /v2/credentials`. Build your own credential collection UI. Replace calls to product endpoints with `POST /v2/tasks/{task_id}/run`. Results arrive via events, not synchronous responses. Create event destinations to receive task results, credential status updates, and other notifications. v2 uses a consistent error format with `type`, `code`, and `message` fields. See the [API Error Handling](/api/errors) page.