Skip to main content
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. Connections, 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
ModelPre-built data products with fixed endpointsGeneral-purpose agents with custom tasks
Auth methodclient_id + secret headersAuthorization: Bearer sk_live_...
Base URLhttps://api.deck.co/https://api.deck.co/v2
User linkingDeck Link (drop-in UI or API)POST /v2/connections with direct credential passing
Token modellink_token → public_token → access_token exchangeSingle connection_id returned directly
Data retrievalCall product-specific endpoints with access_tokenRun tasks against connections, receive structured output via events
MFADedicated security question and MFA endpointsGeneral-purpose interaction system
Output formatFixed response schemas per productCustom output schemas defined per task
WebhooksSingle endpoint, limited event typesMultiple destinations, granular event types, delivery tracking, replay
File accessProduct-specific file download endpointsStorage items with download URLs and optional data extraction

​
Concept mapping

Legacy Conceptv2 ConceptNotes
Data product (Sustainability, Bill, Credit Risk)AgentCreate one agent per use case. You define what it does.
Source (utility provider, bank, etc.)SourceOn 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 sessionConnectionInstead of a multi-step token exchange flow, create a connection 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_tokenConnection ID (conn_)The connection object is the handle for all subsequent operations.
Product endpoint (e.g., /sustainability/statements)Task RunDefine tasks for the data you need. Run them against connections. Results come back as typed JSON.
Statement file downloadStorage itemTasks can produce files. Download them via storage item URLs.
Security question endpointInteractionv2 handles all mid-flow prompts (MFA, security questions, account selection) through one interaction system.
Auto-refreshConnection schedulingv2 supports scheduling on connections 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: 
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 connections: 
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/connections
{
  "source_id": "src_...",
  "auth_method": "username_password",
  "auth_credentials": {
    "username": "user@example.com",
    "password": "..."
  }
}
The response gives you a connection_id immediately. If MFA is required, the connection 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
{
  "connection_id": "conn_...",
  "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.
  • Workflows. Chain multiple tasks together with branching and conditional logic. Replace manual orchestration of multi-step data collection.
  • 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.
  • Event replay. Replay failed deliveries without re-running tasks.
  • Idempotency. All create endpoints accept idempotency keys for safe retries.
  • Prefixed resource IDs. Every ID encodes its type (agt_, conn_, trun_).

​
Migration checklist

1

Create a new Deck account

Sign up at console.deck.co. Legacy accounts cannot be upgraded.
2

Generate a v2 API key

Get your sk_live_ API key from the Dashboard.
3

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.
4

Create sources

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

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.
6

Replace Link with direct connections

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

Update data retrieval logic

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

Set up event destinations

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

Update error handling

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