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

string

required

UUID of the CRM connection.

Response fields

string

required

UUID of the connection.

string

required

CRM platform: "salesforce" or "hubspot".

string

required

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

string

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

string

ISO 8601 timestamp of the most recent successful schema sync.

string

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

string

Human-readable error message from the most recent failure.

string

ISO 8601 timestamp when the connection was first created.

object

Show schemaStats fields

number

Number of CRM object types in the schema cache.

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

{
  "id": "conn_01hx...",
  "platform": "salesforce",
  "status": "active",
  "instanceUrl": "https://myorg.my.salesforce.com",
  "lastSyncAt": "2026-05-15T09:30:00.000Z",
  "lastErrorAt": null,
  "lastErrorMessage": null,
  "createdAt": "2026-01-20T14:00:00.000Z",
  "schemaStats": {
    "objectCount": 4,
    "lastDiscoveredAt": "2026-05-15T09:30:00.000Z"
  }
}

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

string

required

UUID of the CRM connection.

Query parameters

string

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

Response — all objects (no `objectType`)

object[]

required

Array of object summaries.

Show object summary fields

string

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

number

Number of fields discovered for this object.

string

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

string

ISO 8601 timestamp of when the schema was last fetched.

string

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

boolean

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

Response — single object (with `objectType`)

string

required

CRM object name.

object[]

required

Full field metadata array.

Show field metadata

string

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

string

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

string

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

string

Parent object this field belongs to.

string

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

boolean

Whether the field is required by the CRM.

boolean

true for custom fields added by your org.

string

ISO 8601 timestamp of field discovery.

string

required

SHA-256 hash of the field list.

string

required

ISO 8601 timestamp of discovery.

string

required

ISO 8601 timestamp of cache expiry.

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

{
  "objects": [
    {
      "objectType": "Opportunity",
      "fieldCount": 42,
      "schemaHash": "sha256:a1b2c3d4...",
      "discoveredAt": "2026-05-15T09:30:00.000Z",
      "expiresAt": "2026-05-16T09:30:00.000Z",
      "expired": false
    },
    {
      "objectType": "Account",
      "fieldCount": 38,
      "schemaHash": "sha256:e5f6a7b8...",
      "discoveredAt": "2026-05-15T09:30:00.000Z",
      "expiresAt": "2026-05-16T09:30:00.000Z",
      "expired": false
    }
  ]
}

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

{
  "objectType": "Opportunity",
  "fields": [
    {
      "apiName": "Name",
      "label": "Opportunity Name",
      "type": "string",
      "objectType": "Opportunity",
      "platform": "salesforce",
      "required": true,
      "isCustom": false,
      "discoveredAt": "2026-05-15T09:30:00.000Z"
    },
    {
      "apiName": "Amount",
      "label": "Amount",
      "type": "currency",
      "objectType": "Opportunity",
      "platform": "salesforce",
      "required": false,
      "isCustom": false,
      "discoveredAt": "2026-05-15T09:30:00.000Z"
    }
  ],
  "schemaHash": "sha256:a1b2c3d4...",
  "discoveredAt": "2026-05-15T09:30:00.000Z",
  "expiresAt": "2026-05-16T09:30:00.000Z",
  "expired": false
}

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

string

required

UUID of the CRM connection.

Response fields

boolean

required

true when refresh completed successfully.

object[]

required

Updated list of discovered object types and their field counts.

number

required

Total number of fields discovered across all objects.

object[]

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

Show drift fields

string

Object where drift was detected.

string

Name of the field that changed.

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

{
  "success": true,
  "objects": [
    { "objectType": "Opportunity", "fieldCount": 44 },
    { "objectType": "Account", "fieldCount": 38 },
    { "objectType": "Contact", "fieldCount": 29 },
    { "objectType": "Lead", "fieldCount": 31 }
  ],
  "totalFields": 142,
  "drifts": [
    {
      "objectType": "Opportunity",
      "fieldName": "Partner_Source__c",
      "changeType": "added"
    }
  ]
}

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

string

required

UUID of the CRM connection.

Body parameters

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.

object[]

Array of field mapping suggestions.

Show suggestion fields

string

PartnerOS field name.

string

CRM field API name.

number

Confidence score from 0 to 1.

string

"auto_mapped" or "suggested".

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" }'

{
  "suggestions": [
    {
      "partnerosField": "dealAmount",
      "crmField": "Amount",
      "confidence": 0.97,
      "status": "auto_mapped",
      "direction": "bidirectional"
    },
    {
      "partnerosField": "closeDate",
      "crmField": "CloseDate",
      "confidence": 0.95,
      "status": "auto_mapped",
      "direction": "bidirectional"
    },
    {
      "partnerosField": "partnerName",
      "crmField": "Partner_Name__c",
      "confidence": 0.81,
      "status": "suggested",
      "direction": "partneross_to_crm"
    }
  ]
}

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

string

required

UUID of the CRM connection to disconnect.

Response fields

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

{
  "success": true
}

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

​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