Migrating from Sustainability

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 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, telecom, 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 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:

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:

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:

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

# Get all sustainability statements
POST /sustainability/statements
{ "access_token": "..." }

# Get a specific statement file
POST /sustainability/statements/file
{ "access_token": "...", "statement_id": "..." }

v2 pattern

# 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

Create a new Deck account

Generate a v2 API key

Get your sk_live_ API key from the Console.

Create agents for your use cases

Map your legacy data products to agents. A Sustainability integration becomes an agent with tasks for fetching statements, downloading files, etc.

Create sources

Add the websites you were previously connecting to as sources. Provide the URL and Deck handles the rest.

Define tasks with schemas

Create tasks that replicate the data you were fetching from legacy endpoints. Define input and output schemas that match your application’s needs.

Replace Link with direct credentials

Replace the link_token / public_token / access_token exchange flow with POST /v2/credentials. Build your own credential collection UI.

Update data retrieval logic

Replace calls to product endpoints with POST /v2/tasks/{task_id}/run. Results arrive via events, not synchronous responses.

Set up event destinations

Create event destinations to receive task results, credential status updates, and other notifications.

Update error handling

v2 uses a consistent error format with type, code, and message fields. See the API Error Handling page.

Get Started

Guides

Development

Platform

Integrations

Migration Guides

Migrating from Sustainability

New account required

Architecture differences

Concept mapping

Source changes

Authentication changes

Data retrieval changes

Legacy pattern

v2 pattern

What v2 gives you

Migration checklist

​New account required

​Architecture differences

​Concept mapping

​Source changes

​Authentication changes

​Data retrieval changes

​Legacy pattern

​v2 pattern

​What v2 gives you

​Migration checklist

New account required

Architecture differences

Concept mapping

Source changes

Authentication changes

Data retrieval changes

Legacy pattern

v2 pattern

What v2 gives you

Migration checklist