NationGraph CRM Automation Push API
The CRM Automation Push API from NationGraph — 12 operation(s) for crm automation push.
OpenAPI Specification
openapi: 3.1.0
info:
title: Nationgraph Accounts CRM Automation Push API
version: 0.2.36
tags:
- name: CRM Automation Push
paths:
/api/v3/crm/{integration_id}/company-fields:
get:
tags:
- CRM Automation Push
summary: List CRM Company Fields
description: 'List all available fields on the company/account object in the user''s CRM.
Returns field names, labels, types, and whether each is a custom field.
Use this to discover which CRM fields are available when setting up
field mappings for the push endpoint.
- **HubSpot**: Lists all properties on the Companies object
- **Salesforce**: Describes the Account object and returns all fields'
operationId: list_crm_company_fields_api_v3_crm__integration_id__company_fields_get
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CRMFieldResponse'
title: Response List Crm Company Fields Api V3 Crm Integration Id Company Fields Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/pushable-columns:
get:
tags:
- CRM Automation Push
summary: Get Pushable Columns
description: 'Get the list of columns available for CRM push for a given automation.
Each column has a **key** (used in `source_field` of the push request),
a **label**, a **data_type**, and a human-readable **description**.
The available columns depend on the automation type. For `ranked_institutions`:
- `rank` — Institution rank
- `score` — Institution score
- `signal_count` — Number of matching signals'
operationId: get_automation_pushable_columns_api_v3_crm__integration_id__automations__automation_id__pushable_columns_get
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PushableColumnResponse'
title: Response Get Automation Pushable Columns Api V3 Crm Integration Id Automations Automation Id Pushable Columns Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/runs/{run_id}/push-status:
get:
tags:
- CRM Automation Push
summary: Get Push Status
description: 'Check which results from an automation run have already been pushed to
this CRM integration.
Returns per-result push status including when each was last pushed
and which fields were included.'
operationId: get_push_status_api_v3_crm__integration_id__automations__automation_id__runs__run_id__push_status_get
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
- name: run_id
in: path
required: true
schema:
type: string
description: The automation run ID
title: Run Id
description: The automation run ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PushStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/history:
get:
tags:
- CRM Automation Push
summary: Get CRM Push History for an Automation
description: 'Paginated history of every CRM push made by this automation against the
given integration. Ordered by `pushed_at` descending.
Each item includes the institution name, the run the push came from, and
the raw `fields_pushed` payload — the UI derives the activity type from
that payload (e.g. `activity_type: "note"` → Note, otherwise a custom
field push).'
operationId: get_automation_push_history_api_v3_crm__integration_id__automations__automation_id__history_get
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse_PushHistoryItem_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/runs/{run_id}/push:
post:
tags:
- CRM Automation Push
summary: Push Automation Results to CRM
description: "Bulk-push automation run results to CRM companies using explicit field mappings.\n\n**How it works:**\n1. Loads all **completed** results for the specified run\n2. If `result_ids` is provided, narrows to only those results\n3. Filters to results whose institutions have a CRM mapping for this integration\n4. Maps each automation column to the specified existing CRM field\n5. Updates each mapped CRM company with the result data\n6. Records which results were pushed for tracking\n\n**Field mappings** are required. Each entry maps an automation column key\n(from the pushable-columns endpoint) to an existing CRM field name\n(from the company-fields endpoint).\n\n**Selective push** — pass `result_ids` to push only specific results\ninstead of the entire run. Results that are not in `completed` status\nare silently excluded.\n\n**Example request (all results):**\n```json\n{\n \"field_mappings\": [\n {\"source_field\": \"score\", \"crm_field_name\": \"nationgraph_score\"},\n {\"source_field\": \"rank\", \"crm_field_name\": \"ng_rank\"}\n ]\n}\n```\n\n**Example request (selected results only):**\n```json\n{\n \"field_mappings\": [\n {\"source_field\": \"score\", \"crm_field_name\": \"nationgraph_score\"}\n ],\n \"result_ids\": [\"uuid-1\", \"uuid-2\"]\n}\n```\n\n**Requirements:**\n- Active CRM integration (HubSpot or Salesforce)\n- CRM mappings between institutions and CRM companies\n- Target CRM fields must already exist (use company-fields endpoint to verify)\n- Run must have completed results"
operationId: push_automation_results_to_crm_api_v3_crm__integration_id__automations__automation_id__runs__run_id__push_post
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
- name: run_id
in: path
required: true
schema:
type: string
description: The automation run ID
title: Run Id
description: The automation run ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PushAutomationResultsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PushAutomationResultsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/runs/{run_id}/results/{result_id}/push-activity:
post:
tags:
- CRM Automation Push
summary: Push Automation Result as CRM Activity
description: 'Push a single automation result to CRM as a note, task, or post.
Content is automatically generated from the automation result data
(rank, score, signal count, etc.) and formatted per automation type.
**Action types:**
- **`note`**: Records the result summary on the CRM company
- **`task`**: Creates a follow-up task with the result as context
- **`post`**: Creates a Chatter post (Salesforce only)
For tasks and posts, you can override the auto-generated subject/body
via `task_options` or `post_options`.
**Requirements:**
- Active CRM integration (HubSpot or Salesforce)
- CRM mapping between the result''s institution and a CRM company'
operationId: push_automation_result_as_activity_api_v3_crm__integration_id__automations__automation_id__runs__run_id__results__result_id__push_activity_post
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
- name: run_id
in: path
required: true
schema:
type: string
description: The automation run ID
title: Run Id
description: The automation run ID
- name: result_id
in: path
required: true
schema:
type: string
description: The automation result ID
title: Result Id
description: The automation result ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AutomationActivityPushRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CRMActionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/runs/{run_id}/push-signals:
post:
tags:
- CRM Automation Push
summary: Push Automation Run Signals to CRM
description: 'Push the underlying signal content from all CRM-linked results in a ranked
automation run as individual notes or tasks.
For each completed result that has a CRM company mapping, every referenced
signal is resolved to its full content (title, summary, significance, reason)
and pushed using the existing signal-to-CRM push logic.
**Action types:**
- **`note`**: Records each signal as a note on the CRM company
- **`task`**: Creates a follow-up task for each signal
For tasks, you can provide `task_options` to set due date, priority, and owner.
Results without a CRM mapping are silently skipped (reported in `skipped_count`).
**Requirements:**
- Only supported for `ranked_institutions` automation type
- Active CRM integration (HubSpot or Salesforce)
- CRM mappings between institutions and CRM companies
- Run must have completed results'
operationId: push_automation_run_signals_api_v3_crm__integration_id__automations__automation_id__runs__run_id__push_signals_post
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
- name: run_id
in: path
required: true
schema:
type: string
description: The automation run ID
title: Run Id
description: The automation run ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PushSignalsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PushSignalsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/account-layouts:
get:
tags:
- CRM Automation Push
summary: List Account Page Layouts
description: 'List available page layouts on the Account/Company object.
Use this to discover which layout to pass to the custom object schema
creation endpoint so the related list is added to the correct layout.
**Salesforce**: Returns all Account page layouts.
**HubSpot**: Returns an empty list (HubSpot does not have page layouts).'
operationId: list_account_layouts_api_v3_crm__integration_id__account_layouts_get
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CRMAccountLayoutResponse'
title: Response List Account Layouts Api V3 Crm Integration Id Account Layouts Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/custom-object-schemas/{schema_key}:
get:
tags:
- CRM Automation Push
summary: Check Custom Object Schema
description: 'Check whether a custom object schema exists in the user''s CRM.
The `schema_key` determines which NationGraph schema definition to check for.
Currently supported schemas:
- **`vendor_contract`**: NationGraph Vendor Contract custom object
Returns whether the object exists, its provider-specific identifier, and
any expected fields that are missing from the existing object.'
operationId: check_custom_object_schema_api_v3_crm__integration_id__custom_object_schemas__schema_key__get
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: schema_key
in: path
required: true
schema:
type: string
description: Schema identifier (e.g. 'vendor_contract')
title: Schema Key
description: Schema identifier (e.g. 'vendor_contract')
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectSchemaStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- CRM Automation Push
summary: Create Custom Object Schema
description: "Create a custom object schema in the user's CRM workspace.\n\nThe `schema_key` determines which NationGraph schema to create.\nCurrently supported schemas:\n- **`vendor_contract`**: Creates a NationGraph Vendor Contract custom object\n with fields for vendor, product, ACV, dates, summary, institution,\n and a link back to NationGraph. Associated with CRM companies/accounts.\n\n**HubSpot**: Creates a custom object schema with all properties and\ncompany associations via the schemas API.\n\n**Salesforce**: Creates a custom object via the Tooling API, then adds\neach custom field individually, including an Account lookup.\n\nThis endpoint is idempotent-safe — call the check endpoint first to\nverify the schema doesn't already exist."
operationId: create_custom_object_schema_api_v3_crm__integration_id__custom_object_schemas__schema_key__post
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: schema_key
in: path
required: true
schema:
type: string
description: Schema identifier (e.g. 'vendor_contract')
title: Schema Key
description: Schema identifier (e.g. 'vendor_contract')
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectSchemaCreateRequest'
default: {}
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectSchemaCreateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/custom-object-schemas/{schema_key}/spec:
get:
tags:
- CRM Automation Push
summary: Get Custom Object Schema Spec
description: 'Return the full, static definition of a NationGraph custom object schema.
This is the source of truth for manual-setup instructions when a custom object
must be created by hand .'
operationId: get_custom_object_schema_spec_api_v3_crm__integration_id__custom_object_schemas__schema_key__spec_get
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: schema_key
in: path
required: true
schema:
type: string
description: Schema identifier (e.g. 'vendor_contract')
title: Schema Key
description: Schema identifier (e.g. 'vendor_contract')
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomObjectSchemaSpecResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/runs/{run_id}/push-custom-objects:
post:
tags:
- CRM Automation Push
summary: Push Automation Results as Custom Objects
description: 'Push automation run results as individual custom object records in the CRM.
Unlike the regular field-push endpoint (which updates existing CRM company
fields), this creates **new custom object records** — one per result — and
associates each with the corresponding CRM company/account.
**Flow:**
1. Loads completed results for the run (optionally filtered by `result_ids`)
2. Resolves CRM company mappings for each result''s institution
3. Builds custom object properties from the result data
4. Creates records in the CRM with company associations
5. Tracks each push in the `AutomationCRMPush` table
**Requirements:**
- Active CRM integration (HubSpot or Salesforce)
- The custom object schema must already exist (use the schema endpoints)
- CRM mappings between institutions and CRM companies
- Run must have completed results
**Supported automation types:**
- `vendor_contract_enrichment` → `vendor_contract` schema
Each record includes a link back to the NationGraph automation page.'
operationId: push_automation_results_as_custom_objects_api_v3_crm__integration_id__automations__automation_id__runs__run_id__push_custom_objects_post
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
- name: run_id
in: path
required: true
schema:
type: string
description: The automation run ID
title: Run Id
description: The automation run ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PushCustomObjectsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PushCustomObjectsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v3/crm/{integration_id}/automations/{automation_id}/runs/{run_id}/push-contacts:
post:
tags:
- CRM Automation Push
summary: Push Contacts as CRM Contact Records
description: Push a contacts_export run's matched people into the CRM as contact records, each associated to its institution's linked company. Contacts whose institution isn't CRM-linked are skipped (not errors).
operationId: push_run_contacts_api_v3_crm__integration_id__automations__automation_id__runs__run_id__push_contacts_post
security:
- HTTPBearer: []
parameters:
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
description: The CRM integration ID
title: Integration Id
description: The CRM integration ID
- name: automation_id
in: path
required: true
schema:
type: string
description: The automation ID
title: Automation Id
description: The automation ID
- name: run_id
in: path
required: true
schema:
type: string
description: The automation run ID
title: Run Id
description: The automation run ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PushRunContactsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PushRunContactsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
PushStatusResponse:
properties:
total_results:
type: integer
title: Total Results
description: Total completed results in the run
pushed_count:
type: integer
title: Pushed Count
description: Results already pushed to this CRM
unpushed_count:
type: integer
title: Unpushed Count
description: Results not yet pushed
items:
items:
$ref: '#/components/schemas/PushStatusItem'
type: array
title: Items
description: Per-result push status
type: object
required:
- total_results
- pushed_count
- unpushed_count
title: PushStatusResponse
description: Push status for a run+integration pair.
CustomObjectSchemaCreateResponse:
properties:
schema_key:
type: string
title: Schema Key
description: The schema key that was created
provider:
type: string
title: Provider
description: CRM provider (hubspot or salesforce)
object_type_id:
type: string
title: Object Type Id
description: Provider-specific object type identifier
fields_created:
type: integer
title: Fields Created
description: Number of fields created
type: object
required:
- schema_key
- provider
- object_type_id
- fields_created
title: CustomObjectSchemaCreateResponse
description: Response after creating a custom object schema in the CRM.
ContactPushSelector:
properties:
institution_id:
type: string
title: Institution Id
contact_id:
type: string
title: Contact Id
type: object
required:
- institution_id
- contact_id
title: ContactPushSelector
PushCustomObjectsResponse:
properties:
total_results:
type: integer
title: Total Results
description: Total accounts requested (pushed + error + skipped)
linked_count:
type: integer
title: Linked Count
description: Results that had CRM company mappings
pushed_count:
type: integer
title: Pushed Count
description: Accounts successfully created as custom objects
error_count:
type: integer
title: Error Count
description: Accounts that failed to push to CRM
skipped_count:
type: integer
title: Skipped Count
description: Accounts skipped — no CRM mapping, not completed, or no answered questions / data to push
errors:
items:
$ref: '#/components/schemas/PushResultItem'
type: array
title: Errors
description: Details of failed pushes
type: object
required:
- total_results
- linked_count
- pushed_count
- error_count
- skipped_count
title: PushCustomObjectsResponse
description: Summary response from pushing automation results as custom objects.
CRMFieldResponse:
properties:
name:
type: string
title: Name
description: API name of the field
label:
type: string
title: Label
description: Human-readable label
type:
type: string
title: Type
description: Data type (e.g. 'string', 'number')
custom:
type: boolean
title: Custom
description: Whether this is a custom field
type: object
required:
- name
- label
- type
- custom
title: CRMFieldResponse
description: A single field from the user's CRM.
AutomationActivityPushRequest:
properties:
action_type:
$ref: '#/components/schemas/CRMActionType'
description: 'Type of CRM action: ''note'', ''task'', or ''post'''
include_fields:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Include Fields
description: Column keys to include in the generated content body (e.g. ['rank', 'score']). Use the pushable-columns endpoint to discover valid keys. If omitted, all fields are included.
task_options:
anyOf:
- $ref: '#/components/schemas/TaskOptions'
- type: 'null'
description: Options for task creation. Only used when action_type is 'task'.
post_options:
anyOf:
- $ref: '#/components/schemas/PostOptions'
- type: 'null'
description: Options for post creation. Only used when action_type is 'post'.
contact_id:
anyOf:
- type: string
- type: 'null'
title: Contact Id
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nationgraph/refs/heads/main/openapi/nationgraph-crm-automation-push-api-openapi.yml