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.

The Sustainability platform is deprecated. New integrations should be built on v2, and existing Sustainability, Bill, and Credit Risk integrations should move to v2.

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_).

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)	Auth Component (drop-in UI) or `POST /v2/credentials` from your own UI
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 or by polling the task run
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.
Deck Link UI	Auth Component	A drop-in React component that collects credentials, handles MFA, and creates the credential for you. Optional: you can build your own auth flow on the API instead.
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	Trigger	A trigger runs a task or workflow on a cron schedule, fanned out across every credential in scope.

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. If you used the Link UI, the Auth Component is the drop-in equivalent: it collects credentials, handles MFA, and creates the credential without the tokens ever touching your systems. If you built your own UI on the Link API, store the credential 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. The credential starts as unverified and becomes verified the first time a task run authenticates with it. If the source asks for an MFA code or a security question during that run, the task run pauses with status interaction_required and you submit the answer through the interaction endpoint. See Building your auth flow for the full sequence.

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
# Or poll: GET /v2/task-runs/{run_id}
# 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. If you fetched data on a recurring basis, a trigger replaces your own scheduler. It runs a task or workflow on a cron schedule against every credential on a source, and skips accounts that already succeeded within a window you choose.

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.
Workflows. Chain tasks into a multi-step workflow with conditions and loops, so a login, a document fetch, and an extraction run as one unit.
Triggers. Run a task or workflow on a cron schedule across all of your credentials with a trigger. No scheduler on your side.
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

Replace the link_token / public_token / access_token exchange flow. Drop in the Auth Component, or store credentials from your own UI with POST /v2/credentials.

Update data retrieval logic

Replace calls to product endpoints with POST /v2/tasks/{task_id}/run. Results arrive via events, or poll the task run until it completes.

Replace scheduled refreshes with triggers

If you refreshed data on a schedule, create a trigger instead of running your own cron.

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