Supaglue Connections API
A `Connection` represents a Customer's connection to a Provider.
OpenAPI Specification
openapi: 3.0.3
info:
version: 0.25.7
title: Unified CRM Accounts Connections API
contact:
name: Supaglue
email: docs@supaglue.com
url: https://supaglue.com
description: '#### Introduction
Welcome to the Unified API (CRM) documentation. You can use this API to write to multiple third-party providers within the CRM category.
[View common schema for CRM](https://docs.supaglue.com/platform/common-schemas/crm)
#### Base API URL
```
https://api.supaglue.io/crm/v2
```
'
servers:
- url: https://api.supaglue.io/crm/v2
description: Supaglue API
tags:
- name: Connections
description: A `Connection` represents a Customer's connection to a Provider.
paths:
/customers/{customer_id}/connections:
parameters:
- name: customer_id
in: path
required: true
schema:
type: string
get:
operationId: getConnections
tags:
- Connections
security:
- x-api-key: []
summary: List connections
description: Get a list of connections
responses:
'200':
description: Connections
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/connection'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
'409':
$ref: '#/components/responses/conflict'
'422':
$ref: '#/components/responses/unprocessableEntity'
'500':
$ref: '#/components/responses/internalServerError'
'501':
$ref: '#/components/responses/notImplemented'
post:
operationId: createConnection
summary: Create a connection
description: This endpoint is for providers that use API key or access key for authentication. Please use [Embedded Links](https://docs.supaglue.com/platform/managed-auth#oauth-20) for providers that support Oauth2 for authentication.
tags:
- Connections
parameters: []
security:
- x-api-key: []
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
title: apollo
properties:
provider_name:
type: string
enum:
- apollo
example: apollo
type:
type: string
enum:
- api_key
example: api_key
api_key:
type: string
description: API key for the connected customer.
example: e0c5545d-77b8-458d-b4bf-fc701a9cecac
required:
- provider_name
- type
- api_key
- type: object
title: gong
properties:
provider_name:
type: string
enum:
- gong
example: gong
type:
type: string
enum:
- access_key_secret
example: access_key_secret
access_key:
type: string
description: Access key for the connected customer.
example: e0c5545d-77b8-458d-b4bf-fc701a9cecac
access_key_secret:
type: string
description: Access key secret for the connected customer.
example: 258a80aa-2e9b-40b0-8d7a-28f858a856f3
required:
- provider_name
- type
- access_key
- access_key_secret
- type: object
title: salesforce
properties:
provider_name:
type: string
enum:
- salesforce
example: salesforce
type:
type: string
enum:
- oauth2
example: oauth2
refresh_token:
type: string
instance_url:
type: string
login_url:
type: string
required:
- provider_name
- type
- refresh_token
- instance_url
- type: object
title: hubspot
properties:
provider_name:
type: string
enum:
- hubspot
example: hubspot
type:
type: string
enum:
- oauth2
example: oauth2
refresh_token:
type: string
required:
- provider_name
- type
- refresh_token
responses:
'200':
description: Connection created
content:
application/json:
schema:
$ref: '#/components/schemas/connection'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
'409':
$ref: '#/components/responses/conflict'
'422':
$ref: '#/components/responses/unprocessableEntity'
'500':
$ref: '#/components/responses/internalServerError'
'501':
$ref: '#/components/responses/notImplemented'
/customers/{customer_id}/connections/_provider_user_id:
parameters:
- name: customer_id
in: path
required: true
schema:
type: string
get:
operationId: getProviderUserId
summary: Get logged in User ID and details
description: 'This endpoint returns the ID of the logged in (common schema) User and details.
The common schema User ID maps to the following 3rd-party provider object IDs:
| Provider | Remote object ID |
| ---------- | ----------------- |
| Salesforce | User |
| Hubspot | V3 Owner |
| Dynamics | Azure System User |
| Intercom | Admin |
'
tags:
- Connections
security:
- x-api-key: []
parameters:
- name: x-sg-minor-version
in: header
schema:
type: string
enum:
- '1'
example: 1
- name: provider_name
in: query
required: true
schema:
type: string
enum:
- hubspot
- ms_dynamics_365_sales
- intercom
example: hubspot
responses:
'200':
description: UserId
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The ID of the logged in user that originates from your customer's third-party Provider. Refer to the table above for the Provider ID mapping.
raw_details:
type: object
additionalProperties: true
description: The raw data from the your customer's third-party Provider.
additional_raw_details:
type: object
additionalProperties: true
description: For some third-party Providers, there may be additional data used to lookup the common schema User ID (e.g. with Hubspot)
example:
user_id: 70115e3c-2700-4112-b28f-2706e08570e6
raw_details:
user_id: 70115e3c-2700-4112-b28f-2706e08570e6
user: test@something.com
scopes:
- contacts
- automation
- oauth
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
'409':
$ref: '#/components/responses/conflict'
'422':
$ref: '#/components/responses/unprocessableEntity'
'499':
$ref: '#/components/responses/remoteProviderError'
'500':
$ref: '#/components/responses/internalServerError'
'501':
$ref: '#/components/responses/notImplemented'
/customers/{customer_id}/connections/{provider_name}:
parameters:
- name: customer_id
in: path
required: true
schema:
type: string
- name: provider_name
in: path
required: true
schema:
$ref: '#/components/schemas/provider_name'
get:
operationId: getConnection
summary: Get connection
tags:
- Connections
security:
- x-api-key: []
responses:
'200':
description: Connection
content:
application/json:
schema:
$ref: '#/components/schemas/connection'
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
'500':
$ref: '#/components/responses/internalServerError'
'501':
$ref: '#/components/responses/notImplemented'
delete:
operationId: deleteConnection
summary: Delete connection
tags:
- Connections
security:
- x-api-key: []
responses:
'204':
description: An empty body is returned on successful deletion.
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
'409':
$ref: '#/components/responses/conflict'
'422':
$ref: '#/components/responses/unprocessableEntity'
'500':
$ref: '#/components/responses/internalServerError'
'501':
$ref: '#/components/responses/notImplemented'
/customers/{customer_id}/connections/{provider_name}/_rate_limit_info:
parameters:
- name: customer_id
in: path
required: true
schema:
type: string
- name: provider_name
in: path
required: true
schema:
$ref: '#/components/schemas/provider_name'
get:
operationId: getConnectionRateLimitInfo
summary: Get connection rate limit info
description: 'Get rate limit info for a connection. This endpoint is only available for
salesforce and apollo connections.
'
tags:
- Connections
security:
- x-api-key: []
responses:
'200':
description: Connection rate limit info
content:
application/json:
schema:
$ref: '#/components/schemas/rate_limit_info'
components:
schemas:
connection_entity_mapping:
type: object
deprecated: true
properties:
entity_id:
type: string
object:
$ref: '#/components/schemas/standard_or_custom_object'
field_mappings:
type: array
items:
$ref: '#/components/schemas/entity_field_mapping'
required:
- entity_id
object_field_mapping:
type: object
properties:
schema_field:
type: string
example: apolla_first_name
mapped_field:
type: string
example: FirstName
required:
- schema_field
rate_limit_info:
type: object
properties:
daily:
$ref: '#/components/schemas/single_rate_limit_info'
hourly:
$ref: '#/components/schemas/single_rate_limit_info'
other:
type: object
additionalProperties:
$ref: '#/components/schemas/single_rate_limit_info'
category:
type: string
enum:
- crm
- engagement
- enrichment
- marketing_automation
- no_category
example: crm
provider_name:
type: string
enum:
- hubspot
- salesforce
- pipedrive
- zendesk_sell
- ms_dynamics_365_sales
- zoho_crm
- capsule
- outreach
- gong
- apollo
- salesloft
- intercom
- linear
- clearbit
- 6sense
- marketo
- salesforce_marketing_cloud_account_engagement
- slack
example: hubspot
connection_sync_config:
type: object
properties:
destination_config:
description: An object to override the default Destination configuration per connection.
oneOf:
- description: Config specific to Postgres destination
type: object
title: Postgres
properties:
type:
type: string
enum:
- postgres
schema:
type: string
description: The schema you'd like to sync to. This schema must already exist. Supaglue will not create it. If not specified, the schema specified in the Postgres Destination will be used.
example: customer_1_schema
required:
- type
- schema
- description: Config specific to BigQuery destination
type: object
title: BigQuery
properties:
type:
type: string
enum:
- bigquery
dataset:
type: string
description: The dataset you'd like to sync to. This dataset must already exist. Supaglue will not create it. If not specified, the dataset specified in the BigQuery Destination will be used.
example: customer_1_dataset
required:
- type
- dataset
standard_objects:
description: A list of case-sensitive Provider standard objects to by synced. If specified, this list will take override the custom_objects list in SyncConfig.
type: array
items:
oneOf:
- type: object
title: All
properties:
object:
type: string
description: The Provider object name (case sensitive)
example: Contact
required:
- object
- type: object
title: Postgres/BigQuery (Preview)
properties:
object:
type: string
description: The Provider object name (case sensitive)
example: Contact
table:
type: string
description: The table to write the object to. If specified, this will override the default table used by Supaglue.
example: my_contacts
required:
- object
- table
custom_objects:
description: '(Preview) A list of case-sensitive Provider custom objects to be synced. If specified, this list will take override the custom_objects list in SyncConfig.
'
type: array
items:
oneOf:
- type: object
title: All
properties:
object:
type: string
description: The Provider object name (case sensitive)
example: Contact__c
required:
- object
- type: object
title: Postgres/BigQuery (Preview)
properties:
object:
type: string
description: The Provider object name (case sensitive)
example: Contact__c
table:
type: string
description: The table to write the object to. If specified, this will override the default table used by Supaglue.
example: my_contacts
required:
- object
- table
entity_field_mapping:
type: object
deprecated: true
properties:
entity_field:
type: string
description: The name of the field in your application.
example: apolla_first_name
mapped_field:
type: string
description: The name of the field in your customer's third-party Provider tool (e.g. Salesforce).
example: FirstName
required:
- entity_field
- mapped_field
connection:
type: object
properties:
id:
type: string
example: e888cedf-e9d0-42c5-9485-2d72984faef2
application_id:
type: string
example: d8ceb3ff-8b7f-4fa7-b8de-849292f6ca69
customer_id:
type: string
example: my-customer-1
provider_id:
type: string
example: 677fcfca-cf89-4387-a189-71c885be67bc
provider_name:
$ref: '#/components/schemas/provider_name'
category:
$ref: '#/components/schemas/category'
instance_url:
type: string
example: https://app.hubspot.com/contacts/123456
description: Instance URL for the connected customer.
schema_mappings_config:
description: This is for field mappings when you data model using [Objects](https://docs.supaglue.com/platform/objects/overview#schemas). The field mappings here are set by your customers using the [Field Mappings API](https://docs.supaglue.com/api/v2/mgmt/update-object-field-mappings).
type: object
deprecated: true
properties:
common_objects:
type: array
items:
type: object
properties:
object:
type: string
example: Contact__c
field_mappings:
type: array
items:
$ref: '#/components/schemas/object_field_mapping'
required:
- object
- field_mappings
standard_objects:
type: array
items:
type: object
properties:
object:
type: string
example: Contact
field_mappings:
type: array
items:
$ref: '#/components/schemas/object_field_mapping'
example: null
required:
- object
- field_mappings
entity_mappings:
type: array
description: This is for object/field mappings when you data model using [Entities](https://docs.supaglue.com/platform/entities/overview#entity-mapping). The object/field mappings here are set by your customers using the [Entity Mappings API](https://docs.supaglue.com/api/v2/mgmt/upsert-entity-mapping).
deprecated: true
items:
$ref: '#/components/schemas/connection_entity_mapping'
example: []
connection_sync_config:
$ref: '#/components/schemas/connection_sync_config'
required:
- id
- application_id
- customer_id
- provider_id
- provider_name
- category
- instance_url
errors:
type: array
items:
type: object
properties:
id:
type: string
description: A unique identifier for the instance of the error. Provide this to support when contacting Supaglue.
example: 9366efb4-8fb1-4a28-bfb0-8d6f9cc6b5c5
detail:
type: string
description: A detailed description of the error.
example: 'Property values were not valid: [{"isValid":false,"message":"Property \"__about_us\" does not exist","error":"PROPERTY_DOESNT_EXIST","name":"__about_us","localizedErrorMessage":"Property \"__about_us\" does not exist"}]'
problem_type:
type: string
description: The Supaglue error code associated with the error.
example: MISSING_REQUIRED_FIELD
deprecated: true
title:
type: string
description: A brief description of the error. The schema and type of message will vary by Provider.
example: 'Property values were not valid
'
code:
type: string
description: The Supaglue error code associated with the error.
example: MISSING_REQUIRED_FIELD
status:
type: string
description: The HTTP status code associated with the error.
example: '400'
meta:
type: object
description: Additional metadata about the error.
properties:
cause:
type: object
description: The cause of the error. Usually the underlying error from the remote Provider.
example:
code: 400
body:
status: error
message: 'Property values were not valid: [{"isValid":false,"message":"Property \"__about_us\" does not exist","error":"PROPERTY_DOESNT_EXIST","name":"__about_us","localizedErrorMessage":"Property \"__about_us\" does not exist"}]'
correlationId: ac94252c-90b5-45d2-ad1d-9a9f7651d7d2
category: VALIDATION_ERROR
headers:
access-control-allow-credentials: 'false'
cf-cache-status: DYNAMIC
cf-ray: 8053d17b9dae9664-SJC
connection: close
content-length: '361'
content-type: application/json;charset=utf-8
date: Mon, 11 Sep 2023 23:51:22 GMT
nel: '{"success_fraction":0.01,"report_to":"cf-nel","max_age":604800}'
report-to: '{"endpoints":[{"url":"https://a.nel.cloudflare.com/report/v3?s=FgwuXObO%2Fz6ahUJKsxjDLaXTWjooJ8tB0w4%2B%2BKaulGStx0FGkn1PoJoOx2KrFMfihzNdfAqikq7CmgbdlmwKB8hkmp3eTb68qpg10LXFlRgiSqRhbWM7yYSfo8CXmPBc"}],"group":"cf-nel","max_age":604800}'
server: cloudflare
strict-transport-security: max-age=31536000; includeSubDomains; preload
vary: origin, Accept-Encoding
x-content-type-options: nosniff
x-envoy-upstream-service-time: '91'
x-evy-trace-listener: listener_https
x-evy-trace-route-configuration: listener_https/all
x-evy-trace-route-service-name: envoyset-translator
x-evy-trace-served-by-pod: iad02/hubapi-td/envoy-proxy-6c94986c56-9xsh2
x-evy-trace-virtual-host: all
x-hubspot-correlation-id: ac94252c-90b5-45d2-ad1d-9a9f7651d7d2
x-hubspot-ratelimit-interval-milliseconds: '10000'
x-hubspot-ratelimit-max: '100'
x-hubspot-ratelimit-remaining: '99'
x-hubspot-ratelimit-secondly: '10'
x-hubspot-ratelimit-secondly-remaining: '9'
x-request-id: ac94252c-90b5-45d2-ad1d-9a9f7651d7d2
x-trace: 2B1B4386362759B6A4C34802AD168B803DDC1BE770000000000000000000
origin:
type: string
enum:
- remote-provider
- supaglue
description: The origin of the error.
example: remote-provider
application_name:
type: string
description: The name of the application that generated the error.
example: MyCompany Production
required:
- origin
additionalProperties: true
required:
- id
- detail
- problem_type
- title
- code
- status
- meta
example:
- meta:
cause:
code: 400
body:
status: error
message: 'Property values were not valid: [{"isValid":false,"message":"Property \"__about_us\" does not exist","error":"PROPERTY_DOESNT_EXIST","name":"__about_us","localizedErrorMessage":"Property \"__about_us\" does not exist"}]'
correlationId: ac94252c-90b5-45d2-ad1d-9a9f7651d7d2
category: VALIDATION_ERROR
headers:
access-control-allow-credentials: 'false'
cf-cache-status: DYNAMIC
cf-ray: 8053d17b9dae9664-SJC
connection: close
content-length: '361'
content-type: application/json;charset=utf-8
date: Mon, 11 Sep 2023 23:51:22 GMT
nel: '{"success_fraction":0.01,"report_to":"cf-nel","max_age":604800}'
report-to: '{"endpoints":[{"url":"https://a.nel.cloudflare.com/report/v3?s=FgwuXObO%2Fz6ahUJKsxjDLaXTWjooJ8tB0w4%2B%2BKaulGStx0FGkn1PoJoOx2KrFMfihzNdfAqikq7CmgbdlmwKB8hkmp3eTb68qpg10LXFlRgiSqRhbWM7yYSfo8CXmPBc"}],"group":"cf-nel","max_age":604800}'
server: cloudflare
strict-transport-security: max-age=31536000; includeSubDomains; preload
vary: origin, Accept-Encoding
x-content-type-options: nosniff
x-envoy-upstream-service-time: '91'
x-evy-trace-listener: listener_https
x-evy-trace-route-configuration: listener_https/all
x-evy-trace-route-service-name: envoyset-translator
x-evy-trace-served-by-pod: iad02/hubapi-td/envoy-proxy-6c94986c56-9xsh2
x-evy-trace-virtual-host: all
x-hubspot-correlation-id: ac94252c-90b5-45d2-ad1d-9a9f7651d7d2
x-hubspot-ratelimit-interval-milliseconds: '10000'
x-hubspot-ratelimit-max: '100'
x-hubspot-ratelimit-remaining: '99'
x-hubspot-ratelimit-secondly: '10'
x-hubspot-ratelimit-secondly-remaining: '9'
x-request-id: ac94252c-90b5-45d2-ad1d-9a9f7651d7d2
x-trace: 2B1B4386362759B6A4C34802AD168B803DDC1BE770000000000000000000
detail: 'Property values were not valid: [{"isValid":false,"message":"Property \"__about_us\" does not exist","error":"PROPERTY_DOESNT_EXIST","name":"__about_us","localizedErrorMessage":"Property \"__about_us\" does not exist"}]'
problem_type: MISSING_REQUIRED_FIELD
title: 'Property values were not valid
'
code: MISSING_REQUIRED_FIELD
status: '400'
id: 9366efb4-8fb1-4a28-bfb0-8d6f9cc6b5c5
standard_or_custom_object:
type: object
properties:
type:
type: string
enum:
- standard
- custom
name:
type: string
required:
- type
- name
single_rate_limit_info:
type: object
properties:
limit:
type: integer
example: 1000
remaining:
type: integer
example: 900
reset_time:
type: integer
description: The time (in epoch seconds) at which the rate limit will reset. If missing, the rate limit is a sliding window.
example: 1615219200
required:
- limit
- remaining
responses:
conflict:
description: Conflict
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
notImplemented:
description: Not implemented
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
unprocessableEntity:
description: Unprocessable entity
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
badRequest:
description: Bad request
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
notFound:
description: Not found
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
forbidden:
description: Forbidden
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
internalServerError:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
remoteProviderError:
description: Remote provider error
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
securitySchemes:
x-api-key:
type: apiKey
name: x-api-key
in: header
description: API key to allow developers to access the API