Supaglue Properties API
A `Property` is a field in a Provider Object.
OpenAPI Specification
openapi: 3.0.3
info:
version: 0.25.7
title: Unified CRM Accounts Properties 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: Properties
description: A `Property` is a field in a Provider Object.
paths:
/metadata/properties/{object_name}:
parameters:
- $ref: '#/components/parameters/x-customer-id'
- $ref: '#/components/parameters/x-provider-name'
- name: object_name
in: path
required: true
schema:
type: string
example: contact
get:
operationId: listPropertiesPreview
summary: List properties
tags:
- Properties
security:
- x-api-key: []
responses:
'200':
description: List properties
content:
application/json:
schema:
type: object
properties:
properties:
type: array
items:
$ref: '#/components/schemas/property_unified'
required:
- properties
'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'
post:
operationId: createProperty
summary: Create property
description: 'Creates a custom property in the provider and registers it in Supaglue.
:::note
This endpoint is only supported for Salesforce and Hubspot currently.
:::
'
tags:
- Properties
security:
- x-api-key: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_property'
responses:
'201':
description: Create a property
content:
application/json:
schema:
$ref: '#/components/schemas/property_unified'
'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'
/metadata/properties/{object_name}/{property_name}:
parameters:
- $ref: '#/components/parameters/x-customer-id'
- $ref: '#/components/parameters/x-provider-name'
- name: object_name
in: path
required: true
schema:
type: string
description: The name of the object.
example: contact
- name: property_name
in: path
required: true
schema:
type: string
description: The name of the property.
example: email
get:
operationId: getProperty
summary: Get property (preview)
description: ':::note
This feature is only available in Preview to select customers on our Enterprise plan. [Contact us](mailto:team@supaglue.com) for more information.
:::
'
tags:
- Properties
security:
- x-api-key: []
responses:
'200':
description: Get property
content:
application/json:
schema:
$ref: '#/components/schemas/property_unified'
'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: updateProperty
summary: Update property (preview)
description: ':::note
This feature is only available in Preview to select customers on our Enterprise plan. [Contact us](mailto:team@supaglue.com) for more information.
:::
:::note
This endpoint is only supported for Salesforce and Hubspot currently.
:::
'
tags:
- Properties
security:
- x-api-key: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/update_property'
responses:
'200':
description: Create a property
content:
application/json:
schema:
$ref: '#/components/schemas/property_unified'
'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'
/metadata/properties/{object_name}/register:
parameters:
- $ref: '#/components/parameters/x-customer-id'
- $ref: '#/components/parameters/x-provider-name'
- name: object_name
in: path
required: true
schema:
type: string
description: The name of the object.
example: contact
post:
operationId: registerProperty
summary: Register Property (preview)
description: ':::note
This feature is only available in Preview to select customers on our Enterprise plan. [Contact us](mailto:team@supaglue.com) for more information.
:::
Registers a custom property in Supaglue.
This may be useful for custom properties that were already created in the Customer''s provider.
E.g. a custom field has some machine ID for a particular customer that you want to map to `my_custom_field`.
'
tags:
- Properties
security:
- x-api-key: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/register_property'
responses:
'200':
description: Register a property
content:
application/json:
schema:
$ref: '#/components/schemas/property_unified'
'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'
components:
schemas:
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_property:
type: object
properties:
name:
type: string
description: 'The unique identifier to be used to refer to this property across all customers. Supaglue will use this to appropriately map to the provider field ID.
'
example: ticketId
label:
type: string
description: The human-readable name of the property as provided by the third-party Provider.
example: First Name
description:
type: string
description: A description of the field.
is_required:
type: boolean
description: Defaults to false.
example: false
group_name:
type: string
example: supaglue
description: Only applicable for Hubspot. If specified, Supaglue will attempt to attach the field to this group if it exists, or create it if it doesn't. If not specified, Supaglue will create the field in the 'custom_properties' group.
type:
$ref: '#/components/schemas/property_type'
precision:
type: number
description: Only applicable in Salesforce. If not given, will default to 18.
scale:
type: number
description: Only applicable in Salesforce. If not given, will default to 0.
options:
type: array
description: The list of options for a picklist/multipicklist field.
items:
$ref: '#/components/schemas/picklist_option'
required:
- name
- label
- type
property_type:
type: string
enum:
- text
- textarea
- number
- picklist
- multipicklist
- date
- datetime
- boolean
- url
- other
description: "Type of the field.\n\n:::note\n`picklist` and `multipicklist` property types are currently only supported in Salesforce and Hubspot\n:::\n\n:::note\n`url` property type currently is only natively supported in Salesforce.\n:::\n\nSupport:\n\n<table>\n <thead>\n <tr>\n <th>Type</th>\n <th>Hubspot (type-fieldType)</th>\n <th>Salesforce</th>\n <th>Pipedrive</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <td>text</td>\n <td>string-text</td>\n <td>Text</td>\n <td>varchar_auto</td>\n </tr>\n <tr>\n <td>textarea</td>\n <td>string-textarea</td>\n <td>Textarea</td>\n <td>text</td>\n </tr>\n <tr>\n <td>number</td>\n <td>number-number</td>\n <td>Int/Double (depending on scale)</td>\n <td>double</td>\n </tr>\n <tr>\n <td>picklist</td>\n <td>enumeration-select</td>\n <td>Picklist</td>\n <td>enum</td>\n </tr>\n <tr>\n <td>multipicklist</td>\n <td>enumeration-checkbox</td>\n <td>Multipicklist</td>\n <td>set</td>\n </tr>\n <tr>\n <td>date</td>\n <td>date-date</td>\n <td>Date</td>\n <td>date</td>\n </tr>\n <tr>\n <td>datetime</td>\n <td>datetime-date</td>\n <td>Datetime</td>\n <td>date</td>\n </tr>\n <tr>\n <td>boolean</td>\n <td>bool-booleancheckbox</td>\n <td>Checkbox</td>\n <td>enum</td>\n </tr>\n <tr>\n <td>url</td>\n <td>Not Supported</td>\n <td>Url</td>\n <td>Not Supported</td>\n </tr>\n </tbody>\n </table>\n"
update_property:
type: object
properties:
label:
type: string
description: The human-readable name of the property as provided by the third-party Provider.
example: First Name
description:
type: string
description: A description of the field.
is_required:
type: boolean
description: Defaults to false.
example: false
group_name:
type: string
example: supaglue
description: Only applicable for Hubspot. If specified, Supaglue will attempt to attach the field to this group if it exists, or create it if it doesn't.
type:
$ref: '#/components/schemas/property_type'
precision:
type: number
description: Only applicable in Salesforce. If not given, will default to 18.
scale:
type: number
description: Only applicable in Salesforce. If not given, will default to 0.
options:
type: array
description: The list of options for a picklist/multipicklist field.
items:
$ref: '#/components/schemas/picklist_option'
register_property:
type: object
properties:
id:
type: string
description: The machine name of the property as it appears in the third-party Provider.
example: 1234523
name:
type: string
description: 'The unique identifier to be used to refer to this property across all customers. Supaglue will use this to appropriately map to the provider field ID.
'
example: ticketId
required:
- name
- id
property_unified:
type: object
properties:
id:
type: string
description: The machine name of the property as it appears in the third-party Provider.
example: FirstName
custom_name:
type: string
description: Only applicable for custom properties. This represents the unique identifier that can be used to refer to this property across all customers.
label:
type: string
description: The human-readable name of the property as provided by the third-party Provider.
example: First Name
description:
type: string
description: A description of the field.
is_required:
type: boolean
description: Whether or not this field is required. Must be false for Salesforce boolean fields.
example: false
default_value:
description: The default value for the property. Only supported for Salesforce.
oneOf:
- type: string
- type: number
- type: boolean
group_name:
type: string
example: supaglue
description: Only applicable for Hubspot. If specified, Supaglue will attempt to attach the field to this group if it exists, or create it if it doesn't.
type:
$ref: '#/components/schemas/property_type'
precision:
type: number
description: Only applicable in Salesforce. If not given, will default to 18.
scale:
type: number
description: Only applicable in Salesforce. If not given, will default to 0.
options:
type: array
description: The list of options for a picklist/multipicklist field.
items:
$ref: '#/components/schemas/picklist_option'
raw_details:
type: object
description: The raw details of the property as provided by the third-party Provider, if available.
additionalProperties: true
example: {}
required:
- id
- label
- type
picklist_option:
type: object
properties:
label:
type: string
example: Option 1
value:
type: string
example: option_1
description:
type: string
description: A description of this option.
hidden:
type: boolean
description: Defaults to false.
required:
- label
- value
responses:
conflict:
description: Conflict
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'
notFound:
description: Not found
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'
badRequest:
description: Bad request
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'
forbidden:
description: Forbidden
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'
unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/errors'
parameters:
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
x-provider-name:
name: x-provider-name
in: header
schema:
type: string
example: salesforce
description: The provider name
required: true
securitySchemes:
x-api-key:
type: apiKey
name: x-api-key
in: header
description: API key to allow developers to access the API