Links

Entity API

Unleash your entity graph and use your data to power apps far beyond your data warehouse.
Entity API is designed to make your Entities even more valuable by making them easily accessible to the wider app ecosystem. In addition to using Census Syncs to push data to destinations, you can now make your data available to be pulled by your applications.
This opens your data to a whole world of data integration possibilities. A few of the most exciting ones include:
  • App Platform - Build sidebars and micro apps such as Chrome Extension to view user data inside operator consoles.
  • Personalization - Have your web site personalize pages for the users in session, recommending products or offering promotions to users.
  • Enrichment - Use your data to act as an Enrichment Provider for other services. Use your best first-party data wherever you’ve had to rely on spotty third party data in the past.

Set up

Entity API is available for customers on Census’s Platform Plan
The Entity API can be enabled for each Census workspace individually. Once enabled, all Entities within that workspace will be available via the API.
In order to power the API and make responses quick, Census will automatically cache your entity data on Census managed infrastructure. This process will take a few minutes to hours for extremely large data sets when first enabling the Entity API. Going forward, Census will periodically refresh the cache with incremental changes, just like a typical Census sync. This means that some new data may not be immediately available for querying via the Entity API until the cache is refreshed.
Note that this data will be stored in Census infrastructure until the Entity API is disabled. To learn more about how Census handles your data, see our Security & Privacy page.

Using Entity API Endpoints

Authentication - Uses same key as the Management API - This means you shouldn’t use it directly in public code such as javascript on your website. You’ll want to access it server side instead so the key doesn’t leak. A given API key is scoped to a single Census Workspace and all entities within that workspace will be accessible.
API requests should include a standard authentication header of the form:
Authentication: bearer <secret-key>
The Entity API provides two endpoints:
  • List Entities - Provides the set of all entities available via the API
  • Get Entity Record - Retrieve a specific record of an entity based on its primary key.
You can also access these APIs directly with our Postman collection.
Census Entity API Postman Collection.zip
2KB
Binary

List Entities

The List Entities endpoint will return a list of entities that are available through the API as well as their ID which can then be used to construct a query for specific records of an entity type.
GET https://app.getcensus.com/api/v1/entities
Response
{
"data": [
{
"id": 1,
"name": "Users",
"library_id": 1
},
{
"id": 2,
"name": "Companies",
"library_id": 1
},
{
"id": 3,
"name": "Invoices",
"library_id": 2
},
]
}

Get Entity Record

Each entity has its own API endpoint, specific to each. You can see the API on the entities page. You can look up any record of your entity by providing the record_id, which will look up the record by matching against the Primary ID column selected in the Entity definition.
The URL will be of the form:
GET https://app.getcensus.com/api/v1/entities/[ENTITY_ID]/record?record_id=[RECORD_ID]
Response
{
"data": {
"id": "478060",
"created_at": "2018-01-14 15:53:16",
"email": "[email protected]",
"first_name": "Boris",
"last_name": "Jabes",
"title": "CEO"
}
}
​