Links

Destinations

GET /destinations

This endpoint will list all of your connected destinations. For information on objects associated with a destination, query the endpoint for a specific destination as described below.
See Pagination for standard URL parameters and response data.
Request
Response
curl 'https://app.getcensus.com/api/v1/destinations' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "success",
"data": [
{
"id": 12,
"name": "Google Sheets",
"connection_details": {
"service_account_email": "xxxxxxx.iam.gserviceaccount.com"
}
},
{
"id": 6,
"name": "Google Ads Dev",
"connection_details": {
"account_id": 7515011393,
"account_name": "Manager Account Test"
}
},
{
"id": 15,
"name": "Braze",
"connection_details": {
"instance_url": "https://rest.iad-03.braze.com"
}
},
{
"id": 14,
"name": "HubSpot",
"credentials": {}
}
],
"next": "https://app.getcensus.com/api/v1/destinations?page=2&per_page=4",
"pagination": {
"total_records": 7,
"per_page": 4,
"prev_page": null,
"page": 1,
"next_page": 2,
"last_page": 2
}
}
Data Property
Description
List of destinations
A list containing information on each destination. The properties of a destination are described in the next endpoint.

GET /destinations/[ID]

This endpoint lists information on a specific destination.
Request
Response
curl 'https://app.getcensus.com/api/v1/destinations/[ID]' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "success",
"data": {
"id": 15,
"name": "Braze",
"connection_details": {
"instance_url": "https://rest.iad-03.braze.com"
},
"objects": [
{
"label": "User",
"full_name": "user",
"allow_custom_fields": true,
"allow_case_sensitive_field_names": true
},
{
"label": "Event",
"full_name": "event",
"allow_custom_fields": true,
"allow_case_sensitive_field_names": true
}
]
}
}
Data Property
Description
id
The id of this destination.
name
The name of this source.
connection_details
Connection details associated with this source.
objects
A list of objects associated with this source. The properties of an object are described in the objects endpoint below.

GET /destinations/authorize_url

Census now allows you to create OAuth destinations via our Management API using a two-endpoint flow. Note that support for Datadog and Outreach is coming soon. Please contact us if you require support for these destinations.
First, you will direct your user to begin the authorization flow by providing them the authorization url for a specific destination. You will request a destination’s authorization URL via this endpoint. After the user completes authorization in the destination, we will return the user to your provided redirect_uri with the code. You will then pass the code as oauth_code to ourPOST /destinations and PATCH /destinations/[ID] to create or update an OAuth destination connection.
Data Property
Description
type
the type of OAuth destination
redirect_uri
URL that we will redirect to after completing the authorization flow. This URL will contain a code parameter that you will use to create or update a destination. Note that codes can be used only once and some codes have an expiration period.
[other properties]
Zendesk requires a domain value.
If you’d like to use Salesforce Sandbox (optional), you will have to pass an encoded state blob that contains sandbox set to true,i.e. { "sandbox": true }. This base64 URL encoded and passed as a query param, would be state=eyAic2FuZGJveCI6IHRydWUgfQ%3D%3D
Response property
Description
authorize_url
This is a url that you will provide the user which will begin the authorization flow authorization service for the given destination. The authorization flow, if successful, will return a code that you can use in our POST /destinations and PATCH /destinations/[ID]

POST /destinations

This endpoint creates a destination with the given data.
Request
Response
curl --location --request POST 'https://app.getcensus.com/api/v1/destinations' \
--header 'Authorization: Bearer [API_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_connection": {
"name": "Example ActiveCampaign",
"type": "active_campaign",
"credentials": {
"api_token": "example_api_token",
"instance_url": "https://example.activehosted.com"
}
}
}'
{
"status": "created",
"data": {
"id": 90
}
}
Request Property
Description
service_connection
Contains the information for the connection.
Connection Property
Description
type
required. The type of this destination (e.g. zendesk, active_campaign)
credentials
required. See the Credentials properties explained table below
name
The name to assign to this destination
Credentials properties explained
Credentials property
Description
oauth_code
Required for OAuth destinations. We support Hubspot, Salesforce and Zendesk. This is the code query param that you received after completing the authorization flow. The authorization flow can be initiated after retrieving the authorization url. Note that codes can be used only once and some codes have an expiration period.
[other properties]
Non-OAuth destinations require specific credential key values like e.g. api_token, domain).
OAuth destinations may also require additional information to be passed in credentials. For example, Zendesk requires a domain value.
If you’d like to use Salesforce Sandbox, you will have to pass an encoded state string that contains set to true, i.e. { "sandbox": true }. This encoded and passed in the
block would be { "state": "eyAic2FuZGJveCI6IHRydWUgfQ=="
Response Property
Description
status
created or error indicating whether the model was created.
data
Present if successful. An object containing the destination_id
message
Present if error. Contains message describing the error.

PATCH /destinations/[ID]

This endpoint updates a destination with the given ID.
Request
Response
curl --request PATCH 'https://app.getcensus.com/api/v1/destinations/90' \
--header 'Authorization: Bearer [API_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_connection": {
"name": "ActiveCampaign (Example)",
"credentials": {
"api_token": "regenerated_api_token"
}
}
}'
{
"status": "updated",
"data": {
"id": 90,
"name": "ActiveCampaign (Example)",
"type": "active_campaign",
"connection_details": {
"instance_url": "https://example.activehosted.com"
},
"objects": [...]
}
}
Request Property
Description
service_connection
Contains the information for the connection.
Connection Property
Description
name
The name to assign to this destination
credentials
See the Credentials properties explained table below
Credentials properties explained
Credentials property
Description
oauth_code
Required for OAuth destinations. We support Hubspot, Salesforce and Zendesk. This is the code query param that you received after completing the authorization flow. The authorization flow can be initiated after retrieving the authorization url. Note that codes can be used only once and some codes have an expiration period.
[other properties]
Non-OAuth destinations require specific credential key values like e.g. api_token, domain).
OAuth destinations may also require additional information to be passed in credentials. For example, Zendesk requires a domain value.
If you’d like to use Salesforce Sandbox, you will have to pass an encoded state string that contains set to true, i.e. { "sandbox": true }. This encoded and passed in the
block would be { "state": "eyAic2FuZGJveCI6IHRydWUgfQ=="
Response Property
Description
status
updated or error indicating whether the destination was created.
data
Present if successful. An object containing the destination object.
message
Present if error. Contains message describing the error.

DELETE /destinations/[ID]

This endpoint deletes a destination with the given ID.
Request
Response
curl --request DELETE 'https://app.getcensus.com/api/v1/destinations/90' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "deleted"
}
Response Property
Description
status
deleted or 404 indicating whether the model was found and deleted.

POST /destinations/[ID]/refresh_objects

This endpoint queues a job to refresh the list of objects for a destination.
Request
Response
curl --request POST 'https://app.getcensus.com/api/v1/destinations/90/refresh_objects' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"refresh_key": 1647978948
}
Response Property
Description
refresh_key
Contains an id used to query the refresh objects job.

GET /destinations/[ID]/refresh_objects_status

This endpoint checks whether the the job refreshing objects for a destination has completed.
Request
Response
curl 'https://app.getcensus.com/api/v1/destinations/[ID]/refresh_objects_status?refresh_key=[refresh_key]' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "completed"
}
Query Parameter
Description
refresh_key
required. An id provided by the refresh_objects endpoint, used to check whether the refresh objects job has finished.
Response Property
Description
status
Status of the job. Can be either completed or processing.