Supaglue Accounts API
The `Account` Common Object represents a "company" in CRMs.
OpenAPI Specification
openapi: 3.0.3
info:
version: 0.25.7
title: Unified CRM Accounts 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: Accounts
description: The `Account` Common Object represents a "company" in CRMs.
paths:
/accounts:
parameters:
- $ref: '#/components/parameters/x-customer-id'
- $ref: '#/components/parameters/x-provider-name'
post:
operationId: createAccount
summary: Create account
tags:
- Accounts
parameters: []
security:
- x-api-key: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
record:
$ref: '#/components/schemas/create_update_account'
required:
- record
responses:
'201':
description: Account created
content:
application/json:
schema:
type: object
properties:
record:
$ref: '#/components/schemas/created_record'
warnings:
$ref: '#/components/schemas/warnings'
'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'
get:
operationId: listAccounts
summary: List accounts
tags:
- Accounts
security:
- x-api-key: []
parameters:
- $ref: '#/components/parameters/include_raw_data'
- $ref: '#/components/parameters/read_from_cache'
- $ref: '#/components/parameters/modified_after'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/associations_to_fetch'
responses:
'200':
description: Paginated Accounts
content:
application/json:
schema:
type: object
properties:
pagination:
$ref: '#/components/schemas/pagination'
records:
type: array
items:
$ref: '#/components/schemas/account'
required:
- pagination
- records
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
'499':
$ref: '#/components/responses/remoteProviderError'
'500':
$ref: '#/components/responses/internalServerError'
'501':
$ref: '#/components/responses/notImplemented'
/accounts/_upsert:
parameters:
- $ref: '#/components/parameters/x-customer-id'
- $ref: '#/components/parameters/x-provider-name'
post:
operationId: upsertAccount
summary: Upsert account
description: 'Upsert an account. If the account does not exist, it will be created. If the account does exist, it will be updated.
Only supported for Salesforce and Hubspot.
'
tags:
- Accounts
parameters: []
security:
- x-api-key: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
record:
$ref: '#/components/schemas/create_update_account'
upsert_on:
type: object
properties:
key:
type: string
enum:
- domain
- website
description: The key to upsert on. Only `website` is supported for Salesforce, while both `domain` and `website` are supported for Hubspot.
values:
type: array
description: The values to upsert on. If more than one value is provided, it will act as a logical OR. If more than one account is found that matches, then an error will be thrown.
items:
type: string
example: mydomain.com
required:
- key
- values
required:
- record
- upsert_on
responses:
'201':
description: Account upserted
content:
application/json:
schema:
type: object
properties:
record:
$ref: '#/components/schemas/created_record'
warnings:
$ref: '#/components/schemas/warnings'
'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'
/accounts/{account_id}:
parameters:
- $ref: '#/components/parameters/x-customer-id'
- $ref: '#/components/parameters/x-provider-name'
- name: account_id
in: path
required: true
schema:
type: string
example: 0258cbc6-6020-430a-848e-aafacbadf4ae
get:
operationId: getAccount
summary: Get account
tags:
- Accounts
security:
- x-api-key: []
parameters:
- $ref: '#/components/parameters/include_raw_data'
- $ref: '#/components/parameters/associations_to_fetch'
responses:
'200':
description: Account
content:
application/json:
schema:
$ref: '#/components/schemas/account'
examples:
Example:
value:
addresses:
- address_type: BILLING
city: San Francisco
country: CX
postal_code: '94107'
state: CA
street1: 525 Brannan
street2: null
- address_type: BILLING
city: San Francisco
country: US
postal_code: '94107'
state: CA
street1: 525 Brannan
street2: null
description: Integration API
id: 1234
industry: API's
last_activity_at: '2022-02-10T00:00:00Z'
name: Supaglue
number_of_employees: 276000
owner_id: 9377fd4d-d420-4e0b-93ea-789078a3eab4
phone_numbers:
- phone_number: '+14151234567'
phone_number_type: mobile
created_at: '2023-02-27T00:00:00Z'
updated_at: '2023-02-27T00:00:00Z'
website: https://supaglue.com/
'400':
$ref: '#/components/responses/badRequest'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/notFound'
'499':
$ref: '#/components/responses/remoteProviderError'
'500':
$ref: '#/components/responses/internalServerError'
'501':
$ref: '#/components/responses/notImplemented'
patch:
operationId: updateAccount
summary: Update account
tags:
- Accounts
security:
- x-api-key: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
record:
$ref: '#/components/schemas/create_update_account'
required:
- record
responses:
'200':
description: Account updated
content:
application/json:
schema:
type: object
properties:
warnings:
$ref: '#/components/schemas/warnings'
'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'
/accounts/_search:
parameters:
- $ref: '#/components/parameters/x-customer-id'
- $ref: '#/components/parameters/x-provider-name'
post:
operationId: searchAccounts
summary: Search accounts
description: 'Search accounts by name and/or domain. If both are specified, it will perform an AND operation.
Support:
| Provider | Search By |
| --------- | ----------------------- |
| Apollo | name only |
| Salesloft | name, domain |
| Outreach | name, domain |
Note: only `read_from_cache=false` is supported at the moment.
'
tags:
- Accounts
security:
- x-api-key: []
parameters:
- $ref: '#/components/parameters/include_raw_data'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/read_from_cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
filter:
type: object
description: The criteria to upsert on. If both name and domain are specified, it would perform an AND operation. If more than one account is found that matches, then an error will be thrown.
properties:
name:
type: string
description: The name of the account to upsert on. Supported for Outreach, Salesloft, and Apollo.
domain:
type: string
description: The domain of the account to upsert on. Only supported for Outreach and Salesloft.
required:
- filter
responses:
'200':
description: Paginated accounts
content:
application/json:
schema:
type: object
properties:
pagination:
$ref: '#/components/schemas/pagination'
records:
type: array
items:
$ref: '#/components/schemas/account_2'
required:
- pagination
- records
components:
schemas:
lifecycle_stage:
type: string
nullable: true
enum:
- subscriber
- lead
- marketingqualifiedlead
- salesqualifiedlead
- opportunity
- customer
- evangelist
- other
warnings:
type: array
items:
type: object
properties:
detail:
type: string
problem_type:
type: string
title:
type: string
account:
type: object
properties:
addresses:
$ref: '#/components/schemas/addresses'
description:
type: string
nullable: true
example: Integration API
id:
type: string
example: 1234
industry:
type: string
nullable: true
example: API's
last_activity_at:
type: string
nullable: true
format: date-time
example: '2022-02-27T00:00:00Z'
name:
type: string
nullable: true
example: Sample Customer
number_of_employees:
type: integer
nullable: true
example: 276000
owner_id:
type: string
nullable: true
example: d8ceb3ff-8b7f-4fa7-b8de-849292f6ca69
phone_numbers:
$ref: '#/components/schemas/phone_numbers'
lifecycle_stage:
$ref: '#/components/schemas/lifecycle_stage'
website:
type: string
nullable: true
example: https://supaglue.com/
created_at:
type: string
nullable: true
format: date-time
example: '2022-02-27T00:00:00Z'
updated_at:
type: string
nullable: true
format: date-time
example: '2022-02-27T00:00:00Z'
is_deleted:
type: boolean
example: false
last_modified_at:
type: string
format: date-time
example: '2022-02-27T00:00:00Z'
required:
- addresses
- description
- id
- industry
- last_activity_at
- name
- number_of_employees
- owner_id
- phone_numbers
- website
- lifecycle_stage
- created_at
- updated_at
- is_deleted
- last_modified_at
addresses:
type: array
items:
type: object
properties:
address_type:
type: string
enum:
- primary
- mailing
- other
- billing
- shipping
city:
type: string
nullable: true
example: San Francisco
country:
type: string
nullable: true
example: USA
postal_code:
type: string
nullable: true
example: '94107'
state:
type: string
nullable: true
example: CA
street_1:
type: string
nullable: true
example: 525 Brannan
street_2:
type: string
nullable: true
example: null
required:
- address_type
- city
- country
- postal_code
- state
- street_1
- street_2
example:
- address_type: shipping
city: San Francisco
country: US
postal_code: '94107'
state: CA
street_1: 525 Brannan
street_2: null
created_record:
type: object
properties:
id:
type: string
required:
- id
account_2:
type: object
properties:
id:
type: string
example: 54312
owner_id:
type: string
nullable: true
example: 23e640fe-6105-4a11-a636-3aa6b6c6e762
name:
type: string
nullable: true
example: My Company
domain:
type: string
nullable: true
example: mycompany.com
created_at:
type: string
nullable: true
format: date-time
example: '2022-02-27T00:00:00Z'
updated_at:
type: string
nullable: true
format: date-time
example: '2022-02-27T00:00:00Z'
is_deleted:
type: boolean
example: false
last_modified_at:
type: string
format: date-time
example: '2022-02-27T00:00:00Z'
raw_data:
type: object
additionalProperties: true
required:
- id
- owner_id
- name
- domain
- created_at
- updated_at
- is_deleted
- last_modified_at
phone_numbers:
type: array
items:
type: object
properties:
phone_number:
type: string
nullable: true
example: '+14151234567'
phone_number_type:
type: string
enum:
- primary
- mobile
- fax
- other
required:
- phone_number
- phone_number_type
example:
- phone_number: '+14151234567'
phone_number_type: primary
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_update_account:
type: object
properties:
description:
type: string
nullable: true
example: Integration API
industry:
type: string
nullable: true
example: API's
name:
type: string
nullable: true
example: Sample Customer
number_of_employees:
type: integer
nullable: true
example: 276000
website:
type: string
nullable: true
example: https://supaglue.com/
addresses:
$ref: '#/components/schemas/addresses'
phone_numbers:
$ref: '#/components/schemas/phone_numbers'
owner_id:
type: string
nullable: true
example: 9f3e97fd-4d5d-4efc-959d-bbebfac079f5
lifecycle_stage:
$ref: '#/components/schemas/lifecycle_stage'
custom_fields:
$ref: '#/components/schemas/custom_fields'
pagination:
type: object
properties:
next:
type: string
nullable: true
example: eyJpZCI6IjQyNTc5ZjczLTg1MjQtNDU3MC05YjY3LWVjYmQ3MDJjNmIxNCIsInJldmVyc2UiOmZhbHNlfQ==
previous:
type: string
nullable: true
example: eyJpZCI6IjBjZDhmYmZkLWU5NmQtNDEwZC05ZjQxLWIwMjU1YjdmNGI4NyIsInJldmVyc2UiOnRydWV9
total_count:
type: number
example: 100
required:
- next
- previous
custom_fields:
type: object
additionalProperties: true
description: Custom properties to be inserted that are not covered by the common object. Object keys must match exactly to the corresponding provider API.
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'
parameters:
read_from_cache:
name: read_from_cache
in: query
schema:
type: boolean
example: true
description: "Whether to read from Supaglue's Managed Destination cache or to read directly from the provider. \n\n\n**NOTE**: `read_from_cache=true` requires you to have the object synced to the Supaglue Managed Destination.\n"
associations_to_fetch:
name: associations_to_fetch
in: query
schema:
type: array
items:
type: string
example: contact
description: 'List of associated objects to attempt to fetch associations for. Only relevant for hubspot and when `read_from_cache` is false.
'
page_size:
name: page_size
in: query
schema:
type: string
example: 123
description: 'Number of results to return per page. (Max: 1000)'
x-customer-id:
name: x-customer-id
in: header
schema:
type: string
example: my-customer-1
description: The customer ID that uniquely identifies the customer in your application
required: true
include_raw_data:
name: include_raw_data
in: query
schema:
type: boolean
description: Whether to include raw data fetched from the 3rd party provider.
example: true
modified_after:
name: modified_after
in: query
schema:
type: string
format: date-time
description: If provided, will only return objects modified after this datetime. Datetime must be in ISO 8601 format and URI encoded.
example: '2023-02-23T00:00:00Z'
x-provider-name:
name: x-provider-name
in: header
schema:
type: string
example: salesforce
description: The provider name
required: true
cursor:
name: cursor
in: query
schema:
type: string
example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
description: The pagination cursor value
securitySchemes:
x-api-key:
type: apiKey
name: x-api-key
in: header
description: API key to allow developers to access the API