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.

Data Property	Description
List of destinations	A list containing information on each destination. The properties of a destination are described in the next endpoint.

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.

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]

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

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

Response Property	Description
status	`deleted` or `404` indicating whether the model was found and deleted.

Response Property	Description
refresh_key	Contains an `id` used to query the refresh objects job.

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

Sync Runs

Destination Objects

Last modified 1mo ago