Integrations API — connect and manage your CRM data

The Integrations API lets you manage the CRM connections your PartnerOS organization has established with platforms such as Salesforce and HubSpot. You can inspect connection health, retrieve cached CRM field schemas, trigger a fresh schema discovery, get AI-assisted field mapping suggestions, and disconnect a CRM when needed. All integration endpoints require authentication with a valid session and scope data to your active organization. A connectionId always refers to a UUID that PartnerOS assigns when you authorize a CRM integration through the web application.

Get connection status

Returns the current health and metadata of a CRM connection, along with a summary of the cached schema discovery state. GET /api/integrations/{connectionId}/status

Path parameters

connectionId

string

required

UUID of the CRM connection.

Response fields

string

required

UUID of the connection.

platform

string

required

CRM platform: "salesforce" or "hubspot".

status

string

required

Connection status: "active", "error", "disconnected", or "reauth_required".

instanceUrl

string

For Salesforce, the instance URL (e.g. https://myorg.my.salesforce.com). Null for HubSpot.

lastSyncAt

string

ISO 8601 timestamp of the most recent successful schema sync.

lastErrorAt

string

ISO 8601 timestamp of the most recent sync error, if any.

lastErrorMessage

string

Human-readable error message from the most recent failure.

createdAt

string

ISO 8601 timestamp when the connection was first created.

schemaStats

object

Show schemaStats fields

objectCount

number

Number of CRM object types in the schema cache.

lastDiscoveredAt

string

ISO 8601 timestamp of the most recently cached object’s discovery.

Example

curl --request GET \
  --url "https://app.partneros.com/api/integrations/conn_01hx.../status" \
  --header "Content-Type: application/json" \
  --header "Cookie: session_token=<your-session-token>"

Get CRM schema

Returns the cached field schema for a connection. Use the optional objectType query parameter to fetch detailed field metadata for a single CRM object (e.g. Opportunity or Account). Omit it to get a summary listing all discovered objects. GET /api/integrations/{connectionId}/schema Responses from this endpoint carry a Cache-Control: private, max-age=60 header. Clients may cache them for up to 60 seconds.

Path parameters

connectionId

string

required

UUID of the CRM connection.

Query parameters

objectType

string

CRM object type name (e.g. "Opportunity", "Account", "Contact"). When omitted, returns a summary of all cached objects.

Response — all objects (no `objectType`)

objects

object[]

required

Array of object summaries.

Show object summary fields

objectType

string

CRM object name (e.g. "Opportunity").

fieldCount

number

Number of fields discovered for this object.

schemaHash

string

SHA-256 hash of the field list; changes when the CRM schema drifts.

discoveredAt

string

ISO 8601 timestamp of when the schema was last fetched.

expiresAt

string

ISO 8601 timestamp after which the cache is considered stale (typically 24 h after discovery).

expired

boolean

true if the cache entry is past its expiry. Trigger a schema refresh to update.

Response — single object (with `objectType`)

objectType

string

required

CRM object name.

fields

object[]

required

Full field metadata array.

Show field metadata

apiName

string

API-level field name used in CRM queries (e.g. "CloseDate").

label

string

Human-readable field label (e.g. "Close Date").

type

string

Data type (e.g. "date", "string", "currency", "boolean").

objectType

string

Parent object this field belongs to.

platform

string

CRM platform ("salesforce" or "hubspot").

required

boolean

Whether the field is required by the CRM.

isCustom

boolean

true for custom fields added by your org.

discoveredAt

string

ISO 8601 timestamp of field discovery.

schemaHash

string

required

SHA-256 hash of the field list.

discoveredAt

string

required

ISO 8601 timestamp of discovery.

expiresAt

string

required

ISO 8601 timestamp of cache expiry.

expired

boolean

required

Whether the cache is stale.

Example

curl --request GET \
  --url "https://app.partneros.com/api/integrations/conn_01hx.../schema" \
  --header "Content-Type: application/json" \
  --header "Cookie: session_token=<your-session-token>"

curl --request GET \
  --url "https://app.partneros.com/api/integrations/conn_01hx.../schema?objectType=Opportunity" \
  --header "Content-Type: application/json" \
  --header "Cookie: session_token=<your-session-token>"

Refresh CRM schema

Triggers a live schema discovery from the CRM and updates the cache. Use this endpoint when you know the CRM schema has changed or the cached schema is expired. If the connection’s OAuth token has expired, the server automatically attempts a token refresh before retrying the schema pull. POST /api/integrations/{connectionId}/schema/refresh

Path parameters

connectionId

string

required

UUID of the CRM connection.

Response fields

success

boolean

required

true when refresh completed successfully.

objects

object[]

required

Updated list of discovered object types and their field counts.

totalFields

number

required

Total number of fields discovered across all objects.

drifts

object[]

Any schema drift events detected — fields that were added, removed, or changed since the previous discovery.

Show drift fields

objectType

string

Object where drift was detected.

fieldName

string

Name of the field that changed.

changeType

string

"added", "removed", or "modified".

Example

curl --request POST \
  --url "https://app.partneros.com/api/integrations/conn_01hx.../schema/refresh" \
  --header "Content-Type: application/json" \
  --header "Cookie: session_token=<your-session-token>"

Get AI field mapping suggestions

Uses AI-assisted vector similarity to suggest PartnerOS-to-CRM field mappings for a given object pair. You must have a cached schema for the specified CRM object before calling this endpoint. If no embeddings exist for the CRM fields yet, they are generated automatically before the mapping runs. POST /api/integrations/{connectionId}/mapping/ai-suggest

Path parameters

connectionId

string

required

UUID of the CRM connection.

Body parameters

objectPair

string

required

A string identifying the PartnerOS object and CRM object to map, separated by --. For example: "deal_registration--Opportunity" or "partner--Account". Valid PartnerOS object types include "deal_registration" and "partner".

Response

Returns the AI mapping result including suggested field pairs, confidence scores, and recommended sync directions.

suggestions

object[]

Array of field mapping suggestions.

Show suggestion fields

partnerosField

string

PartnerOS field name.

crmField

string

CRM field API name.

confidence

number

Confidence score from 0 to 1.

status

string

"auto_mapped" or "suggested".

direction

string

Suggested sync direction: "partneross_to_crm", "crm_to_partneross", or "bidirectional".

Example

curl --request POST \
  --url "https://app.partneros.com/api/integrations/conn_01hx.../mapping/ai-suggest" \
  --header "Content-Type: application/json" \
  --header "Cookie: session_token=<your-session-token>" \
  --data '{ "objectPair": "deal_registration--Opportunity" }'

Run a schema refresh (POST /api/integrations/{connectionId}/schema/refresh) before requesting AI suggestions if the schema has not been discovered yet or is expired.

Disconnect a CRM

Marks a CRM connection as disconnected and writes an audit log entry. The connection record is retained for historical reference; no data is deleted. POST /api/integrations/{connectionId}/disconnect

Path parameters

connectionId

string

required

UUID of the CRM connection to disconnect.

Response fields

success

boolean

required

true when the connection was marked as disconnected.

Example

curl --request POST \
  --url "https://app.partneros.com/api/integrations/conn_01hx.../disconnect" \
  --header "Content-Type: application/json" \
  --header "Cookie: session_token=<your-session-token>"

Disconnecting a CRM stops future syncs immediately. Any in-flight sync operations may complete, but no new data will flow between PartnerOS and the CRM until you re-authorize the connection.

Overview

Endpoints

Integrations API — connect and manage your CRM data

Get connection status

Path parameters

Response fields

Example

Get CRM schema

Path parameters

Query parameters

Response — all objects (no `objectType`)

Response — single object (with `objectType`)

Example

Refresh CRM schema

Path parameters

Response fields

Example

Get AI field mapping suggestions

Path parameters

Body parameters

Response

Example

Disconnect a CRM

Path parameters

Response fields

Example

Overview

Endpoints

Documentation Index

​Get connection status

​Path parameters

​Response fields

​Example

​Get CRM schema

​Path parameters

​Query parameters

​Response — all objects (no objectType)

​Response — single object (with objectType)

​Example

​Refresh CRM schema

​Path parameters

​Response fields

​Example

​Get AI field mapping suggestions

​Path parameters

​Body parameters

​Response

​Example

​Disconnect a CRM

​Path parameters

​Response fields

​Example

Get connection status

Path parameters

Response fields

Example

Get CRM schema

Path parameters

Query parameters

Response — all objects (no `objectType`)

Response — single object (with `objectType`)

Example

Refresh CRM schema

Path parameters

Response fields

Example

Get AI field mapping suggestions

Path parameters

Body parameters

Response

Example

Disconnect a CRM

Path parameters

Response fields

Example