Supaglue Providers API
A `Provider` is a third-party SaaS tool we can connect to (e.g. Salesforce).
OpenAPI Specification
openapi: 3.0.3
info:
version: 0.25.7
title: Unified CRM Accounts Providers 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: Providers
description: A `Provider` is a third-party SaaS tool we can connect to (e.g. Salesforce).
paths:
/providers:
get:
operationId: getProviders
tags:
- Providers
security:
- x-api-key: []
summary: List providers
description: Get a list of providers
responses:
'200':
description: Providers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/provider'
'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'
post:
operationId: createProvider
summary: Create provider
tags:
- Providers
security:
- x-api-key: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_provider'
responses:
'201':
description: Provider created
content:
application/json:
schema:
$ref: '#/components/schemas/provider'
'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'
/providers/{provider_id}:
parameters:
- name: provider_id
in: path
required: true
schema:
type: string
get:
operationId: getProvider
summary: Get provider
tags:
- Providers
security:
- x-api-key: []
responses:
'200':
description: Provider
content:
application/json:
schema:
$ref: '#/components/schemas/provider'
'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'
put:
operationId: updateProvider
summary: Update provider
tags:
- Providers
security:
- x-api-key: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_provider'
responses:
'200':
description: Provider
content:
application/json:
schema:
$ref: '#/components/schemas/provider'
'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'
delete:
operationId: deleteProvider
summary: Delete provider
tags:
- Providers
security:
- x-api-key: []
responses:
'200':
description: Provider
content:
application/json:
schema:
$ref: '#/components/schemas/provider'
'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'
components:
schemas:
provider_entity_mapping:
type: object
deprecated: true
properties:
entity_id:
type: string
example: apolla_contact
object:
$ref: '#/components/schemas/standard_object'
field_mappings:
type: array
items:
$ref: '#/components/schemas/entity_field_mapping'
required:
- entity_id
provider_name_crm:
type: string
enum:
- hubspot
- salesforce
- pipedrive
- zendesk_sell
- ms_dynamics_365_sales
- zoho_crm
- capsule
provider:
type: object
properties:
id:
type: string
example: 0c4cb91f-e392-46f5-8934-17496371f932
application_id:
type: string
example: 273e1c75-3b6d-439a-9b8e-c6ac407df92a
category:
$ref: '#/components/schemas/category'
auth_type:
type: string
enum:
- oauth2
- api_key
- access_key_secret
example: oauth2
name:
$ref: '#/components/schemas/provider_name'
config:
$ref: '#/components/schemas/create_provider_config'
objects:
$ref: '#/components/schemas/objects'
entity_mappings:
type: array
deprecated: true
description: This is for object/field mappings when you data model using [Entities](https://docs.supaglue.com/platform/entities/overview). The object/field mappings (aka [Entity Mappings](https://docs.supaglue.com/platform/entities/overview#entity-mapping)) here are set by you, the developer, and the mappings apply for all your customers.
items:
$ref: '#/components/schemas/provider_entity_mapping'
required:
- id
- application_id
- category
- auth_type
- name
objects:
type: object
description: This is for field mappings when you data model using [Objects](https://docs.supaglue.com/platform/objects/overview). The field mappings (aka [Schemas](https://docs.supaglue.com/platform/objects/overview#schemas)) here are set by you, the developer, and the mappings apply for all your customers.
properties:
common:
type: array
items:
type: object
properties:
name:
type: string
example: account
schema_id:
type: string
description: If set, will sync these mapped fields into the raw_data column in addition to the common object. If not set, will fetch all fields as is.
example: 328a8cb3-8345-4b02-b661-ee13b4f76806
required:
- name
standard:
type: array
items:
type: object
properties:
name:
type: string
example: Account
schema_id:
type: string
example: 777ea826-5776-4347-9ece-47bbb17ccdd4
required:
- name
update_provider:
oneOf:
- type: object
title: crm
properties:
auth_type:
type: string
enum:
- oauth2
config:
$ref: '#/components/schemas/update_provider_config'
objects:
$ref: '#/components/schemas/objects'
entity_mappings:
type: array
items:
$ref: '#/components/schemas/provider_entity_mapping'
category:
type: string
enum:
- crm
name:
$ref: '#/components/schemas/provider_name_crm'
required:
- auth_type
- config
- category
- name
- type: object
title: engagement
properties:
auth_type:
type: string
enum:
- oauth2
config:
$ref: '#/components/schemas/update_provider_config'
objects:
$ref: '#/components/schemas/objects'
entity_mappings:
type: array
items:
$ref: '#/components/schemas/provider_entity_mapping'
category:
type: string
enum:
- engagement
name:
$ref: '#/components/schemas/provider_name_engagement'
required:
- auth_type
- config
- category
- name
- type: object
title: no category
properties:
auth_type:
type: string
enum:
- oauth2
config:
$ref: '#/components/schemas/update_provider_config'
objects:
$ref: '#/components/schemas/objects'
entity_mappings:
type: array
items:
$ref: '#/components/schemas/provider_entity_mapping'
category:
type: string
enum:
- no_category
name:
$ref: '#/components/schemas/provider_name_no_category'
required:
- auth_type
- config
- category
- name
standard_object:
type: object
properties:
type:
type: string
enum:
- standard
example: standard
name:
type: string
example: Contact
required:
- type
- name
update_provider_config:
type: object
description: An object that stores Oauth2/API key/access key related credentials.
properties:
provider_app_id:
type: string
oauth:
type: object
properties:
oauth_scopes:
type: array
items:
type: string
credentials:
type: object
properties:
oauth_client_id:
type: string
oauth_client_secret:
type: string
required:
- oauth_client_id
- oauth_client_secret
required:
- oauth_scopes
- credentials
required:
- provider_app_id
- oauth
example:
provider_app_id: my_app_id
oauth:
oauth_scopes:
- crm.objects.contacts.read
- crm.objects.companies.read
- crm.objects.deals.read
- crm.objects.owners.read
- crm.objects.contacts.write
- crm.objects.companies.write
- crm.objects.deals.write
credentials:
oauth_client_id: 7393b5a4-5e20-4648-87af-b7b297793fd1
oauth_client_secret: 941b846a-5a8c-48b8-b0e1-41b6d4bc4f1a
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
provider_name_no_category:
type: string
enum:
- intercom
- gong
- linear
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
create_provider:
oneOf:
- type: object
title: crm
properties:
auth_type:
type: string
enum:
- oauth2
config:
$ref: '#/components/schemas/create_provider_config'
objects:
$ref: '#/components/schemas/objects'
category:
type: string
enum:
- crm
name:
$ref: '#/components/schemas/provider_name_crm'
required:
- auth_type
- config
- category
- name
- type: object
title: engagement
properties:
auth_type:
type: string
enum:
- oauth2
config:
$ref: '#/components/schemas/create_provider_config'
objects:
$ref: '#/components/schemas/objects'
category:
type: string
enum:
- engagement
name:
$ref: '#/components/schemas/provider_name_engagement'
required:
- auth_type
- config
- category
- name
- type: object
title: no category
properties:
auth_type:
type: string
enum:
- api_key
category:
type: string
enum:
- no_category
name:
$ref: '#/components/schemas/provider_name_no_category'
required:
- auth_type
provider_name_engagement:
type: string
enum:
- outreach
- apollo
- salesloft
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
create_provider_config:
type: object
description: An object that stores Oauth2/API key/access key related credentials.
properties:
provider_app_id:
type: string
example: my_app_id
use_managed_oauth:
type: boolean
description: 'True: use Supaglue''s OAuth application credentials. False: Use the provided OAuth application credentials.'
example: true
oauth:
type: object
properties:
oauth_scopes:
type: array
items:
type: string
example:
- crm.objects.contacts.read
- crm.objects.companies.read
- crm.objects.deals.read
- crm.objects.owners.read
- crm.objects.contacts.write
- crm.objects.companies.write
- crm.objects.deals.write
credentials:
type: object
properties:
oauth_client_id:
type: string
example: 7393b5a4-5e20-4648-87af-b7b297793fd1
oauth_client_secret:
type: string
example: 941b846a-5a8c-48b8-b0e1-41b6d4bc4f1a
required:
- oauth_client_id
- oauth_client_secret
required:
- oauth_scopes
- credentials
required:
- provider_app_id
- oauth
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'
securitySchemes:
x-api-key:
type: apiKey
name: x-api-key
in: header
description: API key to allow developers to access the API