API V1
Horizontal operations
Horizontal operations allow you to enrich your data by populating specific fields (columns) for existing items (rows). This is useful for tasks like finding email addresses for a list of companies or extracting specific data points from unstructured text.
Overview
There are three main ways to perform horizontal operations:
- Upload only: Inject raw data into your feed without immediate processing.
- Upload and process: Inject raw data and immediately trigger enrichment for specific fields.
- Create: Trigger enrichment on data that already exists in your feed.
Upload only
"Just put the data in."
Use this endpoint to bulk import raw data items into a Cension feed. This does not trigger any AI processing or enrichment; it simply populates the Data table.
- Endpoint: POST /api/horizontal/upload
- Method: POST
- Description: Uploads raw DataOG items to a feed.
Request body
1{
2 "feedId": 123,
3 "projectId": 456,
4 "dataItems": [
5 {
6 "og_id": "unique_id_1",
7 "og_data": "{\"company\": \"Acme Corp\", \"website\": \"acme.com\"}"
8 },
9 {
10 "og_id": "unique_id_2",
11 "og_data": "{\"company\": \"Globex\", \"website\": \"globex.com\"}"
12 }
13 ]
14}Parameters
- feedId (Required): The ID of the feed to upload to.
- projectId (Required): The project ID authorized for this feed.
- dataItems (Required): A list of objects containing at least og_id (unique identifier) and og_data (raw JSON content).
Upload and process
"Put it in and fill it out."
Use this endpoint to upload data and immediately start an enrichment job. This is the most efficient way to process new data in one step.
- Endpoint: POST /api/horizontal/upload-and-process
- Method: POST
- Description: Uploads data and starts a horizontal processing operation for specified fields.
Request body
1{
2 "feedId": 123,
3 "projectId": 456,
4 "fieldIds": [10, 11, 12],
5 "processingMode": "FillEmpty",
6 "dataItems": [
7 {
8 "og_id": "unique_id_1",
9 "og_data": "{\"company\": \"Acme Corp\"}"
10 }
11 ]
12}Parameters
- fieldIds (Optional): List of field IDs to process. If omitted, uses all selected fields in the workspace.
- processingMode: FillEmpty (default), UpdateExisting, or Both.
Create
"Process what's already there."
Use this endpoint to trigger an enrichment job on items that are already in your feed. This is useful for re-processing failed items or filling in new fields you added later.
- Endpoint: POST /api/horizontal/create
- Method: POST
- Description: Starts a horizontal processing operation on existing items.
Request body
1{
2 "feedId": 123,
3 "projectId": 456,
4 "ogIds": ["unique_id_1", "unique_id_2"],
5 "fieldIds": [10, 12],
6 "processingMode": "FillEmpty"
7}Parameters
- ogIds (Required): List of og_ids identifying the existing items to process.
- fieldIds (Required): List of field IDs (columns) to populate.
Append (Upsert)
"Add or update rows with flat JSON."
Use this endpoint to upsert data into your feed using a simplified, flat JSON structure. Each item is matched by its og_id. If the og_id already exists, the row is merged. If it doesn't exist, a new row is created. Unlike the Upload endpoint (which requires a stringified og_data JSON blob), Append accepts clean, flat key-value objects — making it much easier to integrate with.
- Endpoint: POST /api/horizontal/append
- Method: POST
- Description: Upserts flat JSON items into a feed, matched by og_id.
Request body
1{
2 "feedId": 123,
3 "projectId": 456,
4 "items": [
5 {
6 "og_id": "unique_id_1",
7 "company": "Acme Corp",
8 "website": "acme.com"
9 },
10 {
11 "og_id": "unique_id_2",
12 "company": "Globex",
13 "website": "globex.com"
14 }
15 ]
16}Parameters
- feedId (Required): The ID of the feed to append to.
- projectId (Required): The project ID authorized for this feed.
- items (Required): A list of flat JSON objects. Each object must include an og_id field as its unique identifier. All other keys become columns in your dataset.
Response
1{
2 "success": true,
3 "message": "Successfully processed 2 items",
4 "mergeMode": "AddOnly",
5 "itemsInserted": 2,
6 "itemsUpdated": 0,
7 "totalProcessed": 2,
8 "keysAdded": 4,
9 "keysUpdated": 0,
10 "keysSkipped": 0
11}