Build and activate audience segments in the Census Audience Hub - list, fetch, and create segments defined over an entity, then sync those audiences to marketing and advertising destinations.
openapi: 3.0.1
info:
title: Census Management API
description: >-
The Census Management API lets you integrate core Census reverse ETL and data
activation functionality into your workflows. Manage sources, destinations,
syncs, sync runs, datasets/models, connectors, and Audience Hub segments.
Requests are authenticated with a workspace API access token passed as a
Bearer token in the Authorization header. This is a faithful, representative
specification of the public Census Management API; consult the Census API
reference for the authoritative and complete schema.
termsOfService: https://www.getcensus.com/terms
contact:
name: Census Support
url: https://developers.getcensus.com
version: '1.0'
servers:
- url: https://app.getcensus.com/api/v1
description: Census Management API (region-specific base URL may vary)
security:
- bearerAuth: []
tags:
- name: Sources
- name: Destinations
- name: Syncs
- name: Sync Runs
- name: Datasets and Models
- name: Connectors
- name: Segments
paths:
/sources:
get:
operationId: listSources
tags:
- Sources
summary: List sources
description: Returns the source connections configured in the workspace.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/perPage'
responses:
'200':
description: A paginated list of sources.
content:
application/json:
schema:
$ref: '#/components/schemas/SourceList'
post:
operationId: createSource
tags:
- Sources
summary: Create a source
description: Creates a new source connection in the workspace.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SourceCreate'
responses:
'201':
description: The created source.
content:
application/json:
schema:
$ref: '#/components/schemas/SourceResponse'
/sources/{source_id}:
get:
operationId: getSource
tags:
- Sources
summary: Fetch a source
parameters:
- $ref: '#/components/parameters/sourceId'
responses:
'200':
description: A source object.
content:
application/json:
schema:
$ref: '#/components/schemas/SourceResponse'
/sources/{source_id}/objects:
get:
operationId: listSourceObjects
tags:
- Sources
summary: List source objects
description: Lists the tables, views, and models available in the source.
parameters:
- $ref: '#/components/parameters/sourceId'
responses:
'200':
description: A list of source objects.
content:
application/json:
schema:
$ref: '#/components/schemas/SourceObjectList'
/destinations:
get:
operationId: listDestinations
tags:
- Destinations
summary: List destinations
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/perPage'
responses:
'200':
description: A paginated list of destinations.
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationList'
post:
operationId: createDestination
tags:
- Destinations
summary: Create a destination
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationCreate'
responses:
'201':
description: The created destination.
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationResponse'
/destinations/{destination_id}:
get:
operationId: getDestination
tags:
- Destinations
summary: Fetch a destination
parameters:
- $ref: '#/components/parameters/destinationId'
responses:
'200':
description: A destination object.
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationResponse'
/destinations/{destination_id}/objects:
get:
operationId: listDestinationObjects
tags:
- Destinations
summary: List destination objects
description: Lists the objects Census can write to in the destination.
parameters:
- $ref: '#/components/parameters/destinationId'
responses:
'200':
description: A list of destination objects.
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationObjectList'
/connectors:
get:
operationId: listConnectors
tags:
- Connectors
summary: List connectors
description: Lists the connector services Census supports.
responses:
'200':
description: A list of connector services.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorList'
/connectors/{service_name}/object_types:
get:
operationId: listDestinationObjectTypes
tags:
- Connectors
summary: List destination object types
description: >-
Lists the object types available for a given destination connector
service (for example salesforce, hubspot, google_ads).
parameters:
- name: service_name
in: path
required: true
description: The connector service name, e.g. salesforce.
schema:
type: string
responses:
'200':
description: A list of object types for the service.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectTypeList'
/syncs:
get:
operationId: listSyncs
tags:
- Syncs
summary: List syncs
description: Returns the syncs configured in the workspace.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/perPage'
- name: order
in: query
description: Sort order for the results.
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: A paginated list of syncs.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncList'
post:
operationId: createSync
tags:
- Syncs
summary: Create a sync
description: >-
Creates a new sync mapping a source dataset/model to a destination
object with field mappings, an operation, and a schedule.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SyncCreate'
responses:
'201':
description: The created sync.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncResponse'
/syncs/{sync_id}:
get:
operationId: getSync
tags:
- Syncs
summary: Fetch a sync
parameters:
- $ref: '#/components/parameters/syncId'
responses:
'200':
description: A sync object.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncResponse'
patch:
operationId: updateSync
tags:
- Syncs
summary: Update a sync
parameters:
- $ref: '#/components/parameters/syncId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SyncUpdate'
responses:
'200':
description: The updated sync.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncResponse'
delete:
operationId: deleteSync
tags:
- Syncs
summary: Delete a sync
parameters:
- $ref: '#/components/parameters/syncId'
responses:
'200':
description: The sync was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
/syncs/{sync_id}/trigger:
post:
operationId: triggerSync
tags:
- Syncs
summary: Trigger a sync run
description: >-
Triggers a new run of the sync. Returns a sync run id that can be polled
for status. Powers Census orchestration integrations (Airflow, Dagster,
Prefect, dbt Cloud).
parameters:
- $ref: '#/components/parameters/syncId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
force_full_sync:
type: boolean
description: Force a full (non-incremental) sync run.
responses:
'200':
description: The triggered sync run identifier.
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerResponse'
/syncs/{sync_id}/sync_runs:
get:
operationId: listSyncRunsForSync
tags:
- Sync Runs
summary: List sync runs for a sync
parameters:
- $ref: '#/components/parameters/syncId'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/perPage'
responses:
'200':
description: A paginated list of sync runs.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncRunList'
/sync_runs:
get:
operationId: listSyncRuns
tags:
- Sync Runs
summary: List sync runs
description: Lists sync runs across the workspace.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/perPage'
responses:
'200':
description: A paginated list of sync runs.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncRunList'
/sync_runs/{sync_run_id}:
get:
operationId: getSyncRun
tags:
- Sync Runs
summary: Fetch a sync run
parameters:
- name: sync_run_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: A sync run object.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncRunResponse'
/models:
get:
operationId: listModels
tags:
- Datasets and Models
summary: List models
description: Lists the SQL models defined in the workspace.
responses:
'200':
description: A list of models.
content:
application/json:
schema:
$ref: '#/components/schemas/ModelList'
post:
operationId: createModel
tags:
- Datasets and Models
summary: Create a model
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelCreate'
responses:
'201':
description: The created model.
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponse'
/models/{model_id}:
get:
operationId: getModel
tags:
- Datasets and Models
summary: Fetch a model
parameters:
- name: model_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: A model object.
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponse'
patch:
operationId: updateModel
tags:
- Datasets and Models
summary: Update a model
parameters:
- name: model_id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelCreate'
responses:
'200':
description: The updated model.
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponse'
/datasets:
get:
operationId: listDatasets
tags:
- Datasets and Models
summary: List datasets
responses:
'200':
description: A list of datasets.
content:
application/json:
schema:
$ref: '#/components/schemas/ModelList'
post:
operationId: createDataset
tags:
- Datasets and Models
summary: Create a dataset
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelCreate'
responses:
'201':
description: The created dataset.
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponse'
/segments:
get:
operationId: listSegments
tags:
- Segments
summary: List segments
description: Lists Audience Hub segments in the workspace.
responses:
'200':
description: A list of segments.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentList'
post:
operationId: createSegment
tags:
- Segments
summary: Create a segment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentCreate'
responses:
'201':
description: The created segment.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponse'
/segments/{segment_id}:
get:
operationId: getSegment
tags:
- Segments
summary: Fetch a segment
parameters:
- name: segment_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: A segment object.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Workspace API access token passed as a Bearer token.
parameters:
page:
name: page
in: query
description: Page number for paginated results.
schema:
type: integer
default: 1
perPage:
name: per_page
in: query
description: Number of records per page.
schema:
type: integer
default: 25
sourceId:
name: source_id
in: path
required: true
schema:
type: integer
destinationId:
name: destination_id
in: path
required: true
schema:
type: integer
syncId:
name: sync_id
in: path
required: true
schema:
type: integer
schemas:
StatusResponse:
type: object
properties:
status:
type: string
example: success
Pagination:
type: object
properties:
page:
type: integer
per_page:
type: integer
total:
type: integer
Source:
type: object
properties:
id:
type: integer
example: 101
name:
type: string
example: Production Snowflake
type:
type: string
example: snowflake
connection_details:
type: object
additionalProperties: true
created_at:
type: string
format: date-time
SourceCreate:
type: object
required:
- name
- type
properties:
name:
type: string
type:
type: string
example: snowflake
credentials:
type: object
additionalProperties: true
SourceResponse:
type: object
properties:
status:
type: string
example: success
data:
$ref: '#/components/schemas/Source'
SourceList:
type: object
properties:
status:
type: string
example: success
data:
type: array
items:
$ref: '#/components/schemas/Source'
pagination:
$ref: '#/components/schemas/Pagination'
SourceObject:
type: object
properties:
name:
type: string
example: analytics.public.users
type:
type: string
example: table
SourceObjectList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/SourceObject'
Destination:
type: object
properties:
id:
type: integer
example: 202
name:
type: string
example: Salesforce Production
type:
type: string
example: salesforce
created_at:
type: string
format: date-time
DestinationCreate:
type: object
required:
- name
- type
properties:
name:
type: string
type:
type: string
example: salesforce
credentials:
type: object
additionalProperties: true
DestinationResponse:
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/Destination'
DestinationList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Destination'
pagination:
$ref: '#/components/schemas/Pagination'
DestinationObject:
type: object
properties:
label:
type: string
example: Contact
full_name:
type: string
example: contact
DestinationObjectList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/DestinationObject'
Connector:
type: object
properties:
service_name:
type: string
example: salesforce
label:
type: string
example: Salesforce
ConnectorList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Connector'
ObjectType:
type: object
properties:
label:
type: string
example: Lead
full_name:
type: string
example: lead
allows_custom_fields:
type: boolean
ObjectTypeList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/ObjectType'
FieldMapping:
type: object
properties:
from:
type: object
properties:
type:
type: string
example: column
data:
type: string
example: email
to:
type: string
example: Email
is_primary_identifier:
type: boolean
Sync:
type: object
properties:
id:
type: integer
example: 303
label:
type: string
example: Sync Users to Salesforce Contacts
operation:
type: string
enum:
- upsert
- mirror
- append
- update
- create
example: upsert
paused:
type: boolean
schedule_frequency:
type: string
example: hourly
source_attributes:
type: object
additionalProperties: true
destination_attributes:
type: object
additionalProperties: true
mappings:
type: array
items:
$ref: '#/components/schemas/FieldMapping'
created_at:
type: string
format: date-time
SyncCreate:
type: object
required:
- operation
- source_attributes
- destination_attributes
- mappings
properties:
label:
type: string
operation:
type: string
enum:
- upsert
- mirror
- append
- update
- create
source_attributes:
type: object
additionalProperties: true
destination_attributes:
type: object
additionalProperties: true
mappings:
type: array
items:
$ref: '#/components/schemas/FieldMapping'
schedule_frequency:
type: string
example: hourly
SyncUpdate:
type: object
properties:
label:
type: string
paused:
type: boolean
schedule_frequency:
type: string
mappings:
type: array
items:
$ref: '#/components/schemas/FieldMapping'
SyncResponse:
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/Sync'
SyncList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Sync'
pagination:
$ref: '#/components/schemas/Pagination'
TriggerResponse:
type: object
properties:
status:
type: string
example: success
data:
type: object
properties:
sync_run_id:
type: integer
example: 987654
SyncRun:
type: object
properties:
id:
type: integer
example: 987654
sync_id:
type: integer
example: 303
status:
type: string
enum:
- queued
- working
- completed
- failed
- skipped
example: completed
error_message:
type: string
nullable: true
records_processed:
type: integer
example: 12000
records_updated:
type: integer
example: 340
records_failed:
type: integer
example: 2
records_invalid:
type: integer
example: 0
created_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
nullable: true
SyncRunResponse:
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/SyncRun'
SyncRunList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/SyncRun'
pagination:
$ref: '#/components/schemas/Pagination'
Model:
type: object
properties:
id:
type: integer
example: 404
name:
type: string
example: active_users
query:
type: string
example: SELECT id, email, plan FROM analytics.users WHERE active
source_id:
type: integer
example: 101
created_at:
type: string
format: date-time
ModelCreate:
type: object
required:
- name
- query
- source_id
properties:
name:
type: string
query:
type: string
source_id:
type: integer
ModelResponse:
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/Model'
ModelList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Model'
Segment:
type: object
properties:
id:
type: integer
example: 505
name:
type: string
example: High Value Customers
entity:
type: string
example: users
filters:
type: object
additionalProperties: true
created_at:
type: string
format: date-time
SegmentCreate:
type: object
required:
- name
- entity
properties:
name:
type: string
entity:
type: string
filters:
type: object
additionalProperties: true
SegmentResponse:
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/Segment'
SegmentList:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Segment'