Migrate from API V1 to V2

Activations API V1 is deprecated and will be retired on January 15, 2027. API V2 introduces source-based management of Activations resources, and unified access controls.

This guide shows what to change and gives before-and-after examples. For timelines, Terraform, and the Airflow and Prefect integrations, see the Census Migration FAQ.

What changes at a glance

Migration checklist

1. Create an Activations PAT and use it in the Authorization header.
2. Change your base path from /api/v1 to /api/v2.
3. Rename /destinations calls to /activations, /connectors to /activation_types, and /destination_connect_links to /activation_connect_links.
4. Store the activation id (a string) in place of any destination ID, and read group_id where you need it.
5. Add group_id to the requests that now require it: creating activations, datasets, and connect links.
6. Pass activation_id when you create syncs instead of the source and destination connection IDs.
7. Remove calls to workspace, user, and invitation endpoints. Use Fivetran's user and access management APIs instead.
8. Remove calls to source connect links, source models, and topics.
9. Review the renamed endpoints below and update any calls that use them.
10. Test your integration and switch to the V2 API before January 15, 2027.

Authentication

V1 Workspace API calls use a workspace API key. V2 does not use workspace API keys. Every V2 call uses an Activations PAT.

1. Go to your user settings page.
2. Under Personal Access Tokens, click New Token.
3. Name the token and copy it.

V1

curl "https://app.getcensus.com/api/v1/syncs" \
  -H "Authorization: Bearer YOUR_WORKSPACE_API_KEY"

V2

curl "https://app.getcensus.com/api/v2/syncs" \
  -H "Authorization: Bearer YOUR_ACTIVATIONS_PAT"

A PAT has the same permissions as the user who created it. For more detail, see Authentication.

Endpoint mapping

Use these tables to find the V2 endpoint for each V1 endpoint. All V2 paths start with /api/v2 and all V1 paths start with /api/v1. The methods are the same in V1 and V2 unless noted.

Renamed endpoints

Destinations are now activations

Connectors are now activation types

Destination connect links are now activation connect links

Table endpoints previously using a table ID now identify a table by its catalog, schema, and name

The V1 endpoints that use /tables/{table_id} are consolidated to the existing bulk /tables/... endpoints, with query params to identify the table. In V2, pass the table_catalog, table_schema, and table_name query parameters instead of a table ID. For example, replace GET /api/v1/sources/{source_id}/tables/{table_id} with GET /api/v2/sources/{source_id}/tables/columns?table_catalog=<catalog>&table_schema=<schema>&table_name=<table>.

The V1 endpoint returned all of a table's columns in one response. In V2, tables/columns is paginated, so use the page and per_page query parameters to retrieve every column.

Sync run records are now fetched as an export

The V1 /records endpoint is consolidated into the existing /records_export endpoint. Use Fetch records export to retrieve the records synced during a sync run.

The V1 endpoint returned the records in the response and could filter them by primary_identifier, status, and operation. The V2 endpoint returns a list of URLs to Parquet files that contain all records synced during the sync run, including the operation performed and its status.

The export is available only after the sync run has completed. Before then, the endpoint returns an error.

Endpoints with the same path

These V1 endpoints keep their path in V2. Their request and response bodies can still differ, as described in the sections above.

Endpoints with no V2 equivalent

Source connect links will be retired with V1. Topics were previously deprecated, and models have been replaced by datasets. For the workspace, user, and invitation endpoints, see Workspaces and access control.

Workspaces and access control

Resources are tied to groups, not workspaces

In V1, everything lived inside a workspace, and you picked the workspace by choosing its API key. V2 has no workspaces; instead, resources are tied to a group, identified by a group_id such as abundant_giraffe.

Activation sources are uniquely paired with a group. Resources built off of Activation sources (ex. datasets, activations) now have a group_id returned with the resource to identify which group it is associated with.

Workspace, user, and invitation endpoints are removed

The Organization API's workspace, user, and invitation endpoints have no V2 equivalent:

• /workspaces and everything under it, including /workspaces/{id}/api_key, clone, and application_variables
• /users
• /invitations

User and permission management has now been consolidated into Fivetran. Census's standalone organization and workspaces APIs will be retired with V1. To manage users and permissions programmatically, use Fivetran's existing user and access management APIs. They require a separate Fivetran API key.

Destinations are now activations

In V1, a destination was a standalone connection inside a workspace. In V2, destinations are restructured into activations, and every destination-related resource is renamed to match: /destinations becomes /activations, destination connect links become activation connect links, and connectors become activation_types.

An activation is built from two things:

• A group, where each Activation source is uniquely associated with a group
• A target (previously known as a destination connection), such as Salesforce or HubSpot, that is paired with that source.

This means you can no longer create a destination on its own. You create an activation by choosing an existing source's group_id and giving it a new target. See Response body and Creating an activation for the request and response changes.

Response body

The destination object is now an activation. An activation has its own id, name, and group_id. It also has a source object for the source connection and a destination object for the target. The destination object holds the fields that were at the top level of a V1 destination, such as created_at, last_test_succeeded, type, is_file_system_destination, connection_details, and last_test_results.

What changes:

• id is now the activation ID, a string (like glimmering_donkey) instead of an integer.
• name is now the name of the activation, and it is no longer part of the destination object.
• group_id is new.
• source is new.
• All of the V1 destination fields move into the destination object. The destination.id is the ID of the destination connection, as in V1.

V1 response: GET /api/v1/destinations/12

{
  "status": "success",
  "data": {
    "id": 12,
    "name": "Google Sheets",
    "created_at": "2023-07-22T23:42:47.239Z",
    "last_test_succeeded": true,
    "last_tested_at": "2023-07-22T23:45:00.000Z",
    "type": "google_sheets",
    "is_file_system_destination": false,
    "connection_details": {},
    "last_test_results": {
      "steps": []
    }
  }
}

V2 response: GET /api/v2/activations/glimmering_donkey

{
  "status": "success",
  "data": {
    "id": "glimmering_donkey",
    "name": "Google Sheets",
    "group_id": "abundant_giraffe",
    "source": {
      "id": 42,
      "name": "My Snowflake Warehouse",
      "type": "snowflake"
    },
    "destination": {
      "id": 12,
      "created_at": "2023-07-22T23:42:47.239Z",
      "last_test_succeeded": true,
      "last_tested_at": "2023-07-22T23:45:00.000Z",
      "type": "google_sheets",
      "is_file_system_destination": false,
      "connection_details": {},
      "last_test_results": {
        "steps": []
      }
    }
  }
}

Anywhere you stored a destination ID, store the activation id instead. Because the ID is now a string, check that your code and database columns do not assume a number. Read destination fields, such as last_test_succeeded, from the destination object.

Creating an activation

To create an activation, you must say which group it belongs to. The group_id must belong to an existing source connection. Each activation pairs that source with a new destination connection.

V1 request: POST /api/v1/destinations

{
  "service_connection": {
    "name": "My Salesforce Connection",
    "type": "salesforce",
    "credentials": {
      "...": "..."
    }
  }
}

V2 request: POST /api/v2/activations

{
  "activation": {
    "group_id": "abundant_giraffe",
    "name": "My Salesforce Connection",
    "type": "salesforce",
    "credentials": {
      "...": "..."
    }
  }
}

The request body key changes from service_connection to activation. The type is the service_name of an entry returned by GET /api/v2/activation_types that is marked creatable_via_api.

Syncs

When you create a sync, set activation_id instead of destination_attributes.connection_id and source_attributes.connection_id. The activation identifies both the source and destination connections already, so setting them in the request will not change the connection.

Example Request:

{
  "activation_id": "glimmering_donkey",
  "label": "New Signups to Leads",
  "operation": "upsert",
  "destination_attributes": {
    "object": "lead"
  },
  "source_attributes": {
    "type": "table",
    "table_catalog": "analytics",
    "table_schema": "publish",
    "table_name": "contacts"
  },
  "...": "..."
}

Connect links

Connect links let your customers authorize a destination without sharing credentials with you. In V2, destination connect links are called activation connect links, and source connect links are deprecated.

What changes for you:

• Use /activation_connect_links instead of /destination_connect_links.
• When you create a link, pass the group_id of an existing source connection. It is required.
• Responses no longer include destination_id. They include group_id.
• uri and redirect_uri work the same way as before. uri is null after the link expires or is revoked.
• To let a customer reauthorize an existing activation, use POST /activations/{activation_id}/activation_connect_links. In V1, this was POST /destinations/{destination_id}/connect_links.

V1 request: POST /api/v1/destination_connect_links

{
  "type": "hubspot",
  "redirect_uri": "https://example.com/done"
}

V2 request: POST /api/v2/activation_connect_links

{
  "type": "hubspot",
  "group_id": "abundant_giraffe",
  "redirect_uri": "https://example.com/done"
}

If you used source connect links, there is no direct replacement. Create the source connection first, then use its group_id to create an activation connect link.

Webhooks

The webhook endpoints (/webhooks and /webhooks/{webhook_id}), request bodies, and event types are the same as in V1. What changes:

• Responses include a group_id. It identifies the group of the source connection the webhook is associated with.
• Authentication. Use your Activations PAT, as with every other V2 call.

V1 request: POST /api/v1/webhooks

{
  "name": "My Webhook",
  "endpoint": "https://example.com/activations-alerts",
  "events": [
    "sync.alert.raised",
    "sync.alert.resolved"
  ]
}

V2 response: POST /api/v2/webhooks

The request is the same as V1. The response now includes group_id.

{
  "status": "created",
  "data": {
    "id": 123,
    "name": "My Webhook",
    "endpoint": "https://example.com/activations-alerts",
    "events": [
      "sync.alert.raised",
      "sync.alert.resolved"
    ],
    "group_id": "abundant_giraffe",
    "secret": "..."
  }
}

The supported events are unchanged: sync.alert.raised, sync.alert.resolved, sync.triggered, sync.started, sync.completed, sync.success, and sync.failed. The signing secret is returned once, when you create the webhook, so store it securely.

Need help?

• Browse the Activations REST API V2 reference.
• Read the Census Migration FAQ.