Product Docs

Engineering Blog

Census API Reference

API Reference

Back to Census

Get help

This endpoint lists information for a given segment, including information on its molecules (our data structure for recursive constraints).

Fetch segment

A condition on an property of an entity. The property or column will belong to the entity described in the parent relationship molecule. If the basic molecule is top level, the condition is on the entity on which the segment is based on.

Represents the property name when `attribute_type` is property and the column name when `attribute_type` is column.

The type of the attribute for this condition. Options are:
- `property` for entity properties
- `sql` for sql conditions
- `column` for legacy segments


The operator for this molecule. Only certain operators will be valid for a given property type. For example, the `greaterthan` operator can only be applied to numeric values.

If the `attribute_type` is `sql`, then this is a SQL string. Otherwise the value being filtered on.
  - a number for numerical operators
  - a string for string operators
  - a boolean for boolean operators
  - an array for array operators
  - for datetime operators, this could either be a datetime value, a number (for “morethandays” type operators), or a “between” value which is represented as a hash with the following structure `{ bound_one: X, bound_two: Y }`. X and Y are either datetime values, blank (in which case they become the current datetime on the backend), or a string with the following structure "days_ago: Z" where Z is a number (can be decimal).


A condition or set of conditions on a related entity.

Used only for creating conditions on event entities.

The operator to apply to the event constraint

The type of constraint, will always be `occurrences`.

A list of Atomic Molecules, Related Segment Molecules, Relationship Molecules, Molecule Groups and at most one Operation Molecule.

ID for the relationship object that connects both entities

The dataset ID that this segment is associated with.

[Deprecated] The source object id for this segment. You can typically ignore this.

The id of the model that this filter segment is related to (either directly from legacy segments or indirectly via the dataset)

The SQL query associated with this segment.

The cached size of the segment at that particular moment in time.

The unique identifier for this filter segment.

The type of this source object, will always be `segment`.

WorkspaceBearerAuth

Introduction

Learn how to embed Census Reverse ETL in your customer-facing application so you can focus on your core business.

Overview

This guide will walk you through the available custom branding options for Census Embedded customers.

Custom Branding

Census suggests managing multi-tenancy by using individual workspaces to isolate resources and effectively track usage.

This guide will walk you through using Workspace Variables and Workspace Cloning to implement a template flow.

Template Workspaces

Census provides an in-app usage tracking dashboard to help you monitor and manage each customer's usage of Census.

Workspace Usage Tracking

Learn how to make you and your customers successful using Census.

What's in this guide?

Current Sync Run Overview

Sync History

Row-by-row visibility into your sync runs

Sync Tracking

API Inspector

Sync Alerts

Observability Lake

Datadog Integration

Warehouse Writeback

Sync Dry Runs

Use Census with Custom Destinations to create a connection to any destination service of your choice.

Destination Spec

Publish your Custom Destination to your workspace or organization for convenient repeated use.

Scoped Destinations

Publish your Custom Destination as an officially registered destination, available for all Census users.

Partner Destinations

Unleash your semantic graph and use your data to power apps far beyond your data warehouse.

Guide

Manage Census SQL models and syncs via YAML files in your Git repository.

An introduction to Census' Management APIs

Pagination

Authentication

Paginated list of all user details for the current organization.

List Users

Fetch User

Remove User

Update a user's role within the organization.

Update User Role

Get details for all claimed and unclaimed invitations in the current organization.

List invitations

Retrieve details of a specific invitation.

Fetch invitation

Create a new invitation for a user to join the current organization.

Create invitation

Update an unclaimed invitation's role within the organization.

Update invitation

Revoke an unclaimed invitation so it can no longer be used.

Revoke invitation

Resend the email for an unclaimed invitation.

Resend invitation

Get details for all workspaces in the current organization.

List workspaces

Create a new workspace in the current organization.

Create workspace

Retrieve the details of a specific workspace.

Fetch workspace

Retrieve the details of the workspace authenticated with the current Workspace API Token.

Fetch authenticated workspace

Update workspace

Delete a specific workspace and all of its associated objects. Be very careful!

Delete workspace

Clones a specific workspace in your organization, copying over connections and datasets from the original workspace. If you have connections or datasets that use workspace variables, those will be honored in the new workspace.

Clone workspace

Fetch clone status

List Syncs

Create a new sync

Fetch sync

Update certain configurable attributes of a sync. Note that though this endpoint is a `PATCH` and top level attributes respect patch semantics, this does not apply to nested objects. Any nested objects that are changed must be sent in full, including any unchanged values.

Update a sync

Delete a sync

Triggers the sync with the specified ID to start a new sync run.

Trigger a sync run

This endpoint returns details for all active and expired sync management links in the current workspace. Read more on how to use Sync Management links in our [Census Embedded How-to Guides](/embedded/features/sync-management-links/sync-management-links).

List sync management links

Sync Management links allow your customers to seamlessly configure which data to import or export. Read more on how to use Sync Management links in our [Census Embedded How-to Guides](/embedded/features/sync-management-links/sync-management-links).

Create a new sync management link

Retrieve the details of a specific sync management link. Read more on how to use Sync Management links in our [Census Embedded How-to Guides](/embedded/features/sync-management-links/sync-management-links).

Fetch sync management link

Revokes a sync management link so that it can no longer be used. Read more on how to use Sync Management links in our [Census Embedded How-to Guides](/embedded/features/sync-management-links/sync-management-links).

Revoke a sync management link

This link URI is used to edit a sync. Read more on how to use Sync Management links in our [Census Embedded How-to Guides](/embedded/features/sync-management-links/sync-management-links).

Create sync management link to edit a sync

List sync runs

Retrieve the details of a particular sync run

Fetch sync run

Use this endpoint to cancel a sync that is actively running.

Cancel a running sync

Use this endpoint to retrieve a sample of skipped records for a specific sync run.
The endpoint will redirect to a temporary S3 URL where the JSON file contents can be accessed.
Clients should follow the redirect to retrieve the JSON data.

This is initially a 302 redirect to the skipped records file, and if followed ultimately returns a 200 with the JSON data in the response. The schema of the return will vary depending on the fields used in the sync. The sync key will be used to identify a record with an `error_message`. Additional properties will be returned matching the fields used in the sync.

The endpoint may also return a 410 if the skipped records file is no longer available. You can read more about how we handle skipped records and our [policy on expiration: here](https://docs.getcensus.com/basics/security-and-privacy#step-4-report-skipped-records-and-feedback-to-warehouse).


Fetch sample skipped records

Retrieves records synced during a given sync run. A primary_identifier can be specified to fetch information about a single record. Additional filters such as operation and status are available as well.

Fetch Records

Retrieves the count of all records synced during a given sync run. Filters can be applied to get specific counts.

Fetch Records Count

Retrieves a list of URLs to Parquet files containing all records synced during a given sync run, including the operation performed and the status of that operation.

Fetch Records Export

Use this endpoint to list out the types of destination connections that can be created in the current workspace. This is particularly useful for Census Embedded solutions when determining the required values to authorize a new destination connection.

List destination types

Create a new destination type for your given workspace. By default the destination type is created and scoped just to your workspace and not visible to other workspaces or orgs. See [Scoped Destinations](/custom-destinations/scoped-destinations) and [Partner Destinations](/custom-destinations/partner-destinations) for more information on how to create destination types that are visible to other workspaces or orgs.

Create a new destination type

Use this endpoint to fetch the details for a specific types of destination connection that can be created in the current workspace. This is particularly useful for Census Embedded solutions when determining the required values to authorize a new destination connection.

Fetch destination type

Update a specific destination type by service name. You must be an owner of the destination type and it must not be published in order to update. If you wish to update a published destination type please reach out to Census Support.

Update destination type

Publish a destination type to the organization. This will make the destination type available to all workspaces in the organization. You must be an owner of the destination type and it must not be already published. See [Scoped Destinations](/custom-destinations/scoped-destinations) for more details. For information on publishing to all Census customers, see [Partner Destinations](/custom-destinations/partner-destinations).

Publish destination type to organization

Delete a specific destination type by service name. You must be an owner of the destination type and it must not be published in order to delete. If you wish to delete a published destination type please reach out to Census Support.

Delete destination type

List destination object types

List destinations

This endpoint can be used to create destinations in Census. Each destination requires a different set of credentials in the request payload. 
The credentials needed to create each type of connection can be found in the `GET /connectors` API for most destinations. For OAuth destinations, see this [Notion doc](https://getcensus.notion.site/Headless-OAuth-Destinations-4b282c9944fe4fa3a5d76d874f0c3d5f).


Create a new destination

Fetch destination

Update destination

Delete destination

This endpoint returns details for all active and expired connect links in the current workspace. Read more on how to use Connect links in our [Census Embedded How-to Guides](/embedded/features/connect-links/connect-links).

List destination connect links

Create a new destination connect link, which can be used to collect your customers' credentials. Read more on how to use Connect links in our [Census Embedded How-to Guides](/embedded/features/connect-links/connect-links).

Create a new destination connect link

Retrieve the details of a specific destination connect link. Read more on how to use Connect links in our [Census Embedded How-to Guides](/embedded/features/connect-links/connect-links).

Fetch destination connect link

Revokes a destination connect link so that it can no longer be used. Read more on how to use Connect links in our [Census Embedded How-to Guides](/embedded/features/connect-links/connect-links).

Revoke a destination connect link

This link URI is used to reauthorize your destination.

Create connect link to reauthorize destination

List source types

Use this endpoint to fetch the details for a specific type of source connection that can be created in the current workspace. This is particularly useful for Census Embedded solutions when determining the required values to authorize a new source connection.

Fetch source type

List sources

Create a new source

Fetch source

Update source

Delete source

List source connect links

Create a new source connect link, which can be used to collect your customers' credentials. Read more on how to use Connect links in our [Census Embedded How-to Guides](/embedded/features/connect-links/connect-links).

Create a new source connect link

Retrieve the details of a specific source connect link. Read more on how to use Connect links in our [Census Embedded How-to Guides](/embedded/features/connect-links/connect-links).

Fetch source connect link

Revokes a source connect link so that it can no longer be used. Read more on how to use Connect links in our [Census Embedded How-to Guides](/embedded/features/connect-links/connect-links).

Revoke a source connect link

This link URI is used to reauthorize your source.

Introduction

Organization APIs

Workspace APIs

Fetch segment

Authorizations

Path Parameters

Response