Ampersand Objects & Fields API
The Objects & Fields API from Ampersand — 4 operation(s) for objects & fields.
OpenAPI Specification
openapi: 3.0.1
info:
title: Ampersand public API Key Objects & Fields API
version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
security:
- APIKeyHeader: []
- Bearer: []
tags:
- name: Objects & Fields
paths:
/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/metadata:
get:
summary: Ampersand Get Object Metadata via Installation
description: 'Retrieves metadata about an object in a customer''s SaaS instance, including its fields. An installation must exist for the given `groupRef` and `integrationId`. The `objectName` can be either the mapped name from your integration config or the native provider name. For Salesforce, nested fields may be included using JSONPath bracket notation (e.g. `$[''billingaddress''][''city'']`).
'
tags:
- Objects & Fields
operationId: getObjectMetadataForInstallation
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The unique identifier of the integration.
schema:
type: string
example: e3a7f9c1-4b2d-4e8a-9f6b-2d5c8a1e3b7f
- name: objectName
in: path
required: true
description: 'The name of the object to retrieve metadata for. You can use either the mapped name from your integration config (e.g. `people`) or the native provider object name (e.g. `contact`).
'
schema:
type: string
example: account
- name: groupRef
in: query
required: true
description: The ID of the user group that has access to this installation.
example: group-123
schema:
type: string
- name: excludeReadOnly
in: query
required: false
description: Excludes fields where `ReadOnly` is `true` from the response.
example: true
schema:
type: boolean
responses:
'200':
description: The retrieved object metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectMetadata'
example:
name: account
displayName: Account
mappedObjectName: companies
fields:
name:
fieldName: name
displayName: Account Name
valueType: string
providerType: string
readOnly: false
isCustom: false
isRequired: true
billingcity:
fieldName: billingcity
displayName: Billing City
valueType: string
providerType: string
readOnly: false
isCustom: false
isRequired: false
industry:
fieldName: industry
displayName: Industry
valueType: singleSelect
providerType: picklist
readOnly: false
isCustom: false
isRequired: false
values:
- value: technology
displayValue: Technology
- value: finance
displayValue: Finance
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
/projects/{projectIdOrName}/providers/{provider}/objects/{objectName}/metadata:
get:
summary: Ampersand Get Object Metadata via Connection
description: 'Retrieves metadata about an object in a customer''s SaaS instance, including its fields. A connection must exist for the given `groupRef` and `provider`. For Salesforce, nested fields may be included using JSONPath bracket notation (e.g. `$[''billingaddress''][''city'']`).
'
tags:
- Objects & Fields
operationId: getObjectMetadataForConnection
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: provider
in: path
required: true
description: The provider name (e.g. `salesforce`, `hubspot`).
schema:
type: string
example: salesforce
- name: objectName
in: path
required: true
description: The native provider object name to retrieve metadata for.
schema:
type: string
example: contact
- name: groupRef
in: query
required: true
description: The ID of the user group whose connection should be used to fetch the metadata.
example: group-123
schema:
type: string
- name: excludeReadOnly
in: query
required: false
description: Excludes fields where `ReadOnly` is `true` from the response.
example: true
schema:
type: boolean
responses:
'200':
description: The retrieved object metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectMetadata'
example:
name: contact
displayName: Contact
fields:
firstname:
fieldName: firstname
displayName: First Name
valueType: string
providerType: string
readOnly: false
isCustom: false
isRequired: true
email:
fieldName: email
displayName: Email
valueType: string
providerType: string
readOnly: false
isCustom: false
isRequired: false
lifecyclestage:
fieldName: lifecyclestage
displayName: Lifecycle Stage
valueType: singleSelect
providerType: enumeration
readOnly: false
isCustom: false
isRequired: false
values:
- value: lead
displayValue: Lead
- value: customer
displayValue: Customer
default:
description: Error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
/projects/{projectIdOrName}/integrations/{integrationId}/object-metadata:
put:
summary: Ampersand Upsert Custom Fields for Installation
operationId: upsertMetadataForInstallation
description: Create or update fields in the SaaS instance tied to an installation. Only HubSpot and Salesforce are supported currently.
tags:
- Objects & Fields
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: integrationId
in: path
required: true
description: The integration ID.
schema:
type: string
example: 32356abe-d2fd-49c7-9030-abdcbc6456d4
requestBody:
required: true
description: Metadata upsert request containing field definitions to create or update
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertMetadataRequest'
examples:
createTextFields:
summary: Create text fields on multiple objects
value:
groupRef: group-123
fields:
Account:
- fieldName: Industry
displayName: Industry Sector
description: The industry this account operates in
valueType: string
required: false
stringOptions:
length: 255
defaultValue: Technology
- fieldName: Company_Size
displayName: Company Size
valueType: string
stringOptions:
values:
- Small
- Medium
- Large
- Enterprise
valuesRestricted: true
Contact:
- fieldName: Seniority_Level
displayName: Seniority Level
valueType: string
stringOptions:
values:
- Junior
- Mid
- Senior
- Executive
valuesRestricted: true
createNumericFields:
summary: Create numeric fields with constraints
value:
groupRef: group-123
fields:
Opportunity:
- fieldName: Deal_Score
displayName: Deal Score
description: Likelihood score from 0-100
valueType: float
required: true
numericOptions:
precision: 5
scale: 2
min: 0
max: 100
defaultValue: 50
createAssociationField:
summary: Create field with association to another object
value:
groupRef: group-123
fields:
Task:
- fieldName: Related_Contact
displayName: Related Contact
valueType: string
association:
associationType: lookup
targetObject: Contact
targetField: Id
cardinality: many-to-one
required: false
labels:
singular: Contact
plural: Contacts
responses:
'200':
description: Metadata creation completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertMetadataResponse'
'400':
description: Invalid request payload or validation errors
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'401':
description: Authentication required
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'403':
description: Insufficient permissions for metadata operations
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'404':
description: Project, integration, or installation not found
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'500':
description: Internal server error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
/projects/{projectIdOrName}/providers/{provider}/object-metadata:
put:
summary: Ampersand Upsert Custom Fields for Connection
operationId: upsertMetadataForConnection
description: Create or update fields in the SaaS instance tied to a connection. Only HubSpot and Salesforce are supported currently.
tags:
- Objects & Fields
parameters:
- name: projectIdOrName
in: path
required: true
description: The Ampersand project ID or project name.
schema:
type: string
example: my-project
- name: provider
in: path
required: true
description: The provider that this connection connects to.
schema:
type: string
example: salesforce
requestBody:
required: true
description: Metadata upsert request containing field definitions to create or update
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertMetadataRequest'
examples:
createTextFields:
summary: Create text fields on multiple objects
value:
groupRef: group-123
fields:
Account:
- fieldName: Industry
displayName: Industry Sector
description: The industry this account operates in
valueType: string
required: false
stringOptions:
length: 255
defaultValue: Technology
- fieldName: Company_Size
displayName: Company Size
valueType: string
stringOptions:
values:
- Small
- Medium
- Large
- Enterprise
valuesRestricted: true
Contact:
- fieldName: Seniority_Level
displayName: Seniority Level
valueType: string
stringOptions:
values:
- Junior
- Mid
- Senior
- Executive
valuesRestricted: true
createNumericFields:
summary: Create numeric fields with constraints
value:
groupRef: group-123
fields:
Opportunity:
- fieldName: Deal_Score
displayName: Deal Score
description: Likelihood score from 0-100
valueType: float
required: true
numericOptions:
precision: 5
scale: 2
min: 0
max: 100
defaultValue: 50
createAssociationField:
summary: Create field with association to another object
value:
groupRef: group-123
fields:
Task:
- fieldName: Related_Contact
displayName: Related Contact
valueType: string
association:
associationType: lookup
targetObject: Contact
targetField: Id
cardinality: many-to-one
required: false
labels:
singular: Contact
plural: Contacts
responses:
'200':
description: Metadata creation completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertMetadataResponse'
'400':
description: Invalid request payload or validation errors
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'401':
description: Authentication required
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'403':
description: Insufficient permissions for metadata operations
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'404':
description: Project or connection not found
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'500':
description: Internal server error
content:
application/problem+json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
components:
schemas:
ObjectMetadata:
title: Object Metadata
type: object
required:
- name
- fields
properties:
name:
type: string
description: The provider name of the object
example: contact
displayName:
type: string
description: Human-readable name of the object
example: Contact
mappedObjectName:
type: string
description: The mapped name of the object as defined in your integration config, if a mapping was applied. Only present when using the installation-scoped metadata endpoint.
example: people
fields:
type: object
description: Map of field metadata keyed by field name
additionalProperties:
$ref: ../manifest/manifest.yaml#/components/schemas/FieldMetadata
AssociationDefinition:
type: object
description: Relationship information for a field to another object
properties:
associationType:
type: string
description: High-level association variety (e.g., 'foreignKey', 'lookup', 'ref')
example: foreignKey
targetObject:
type: string
description: Name of the referenced/parent object
example: Account
targetField:
type: string
description: Name of the referenced field on the target object
cardinality:
type: string
description: Association cardinality from the referencing field's perspective
example: many-to-one
onDelete:
type: string
description: Behavior upon foreign object deletion
example: setNull
required:
type: boolean
description: If true, a referenced record must exist
reverseLookupFieldName:
type: string
description: Optional inverse relationship/property name exposed on the target object
labels:
$ref: '#/components/schemas/AssociationLabels'
required:
- associationType
- targetObject
UpsertMetadataResponse:
type: object
description: Response containing results for all created/updated fields
properties:
success:
type: boolean
description: Indicates if the upsert operation was successful
fields:
type: object
description: Maps object name -> field name -> upsert result
additionalProperties:
type: object
additionalProperties:
$ref: '#/components/schemas/FieldUpsertResult'
required:
- success
- fields
FieldUpsertResult:
type: object
description: Result of an upsert operation for a single field
properties:
fieldName:
type: string
description: Name of the field
action:
type: string
description: Action taken (create, update, none)
metadata:
type: object
description: Provider-specific metadata about the field
additionalProperties: true
warnings:
type: array
description: Warnings that occurred during the upsert operation
items:
type: string
required:
- fieldName
- action
AssociationLabels:
type: object
description: UI labels for an association
properties:
singular:
type: string
description: Singular display label
plural:
type: string
description: Plural display label
StringFieldOptions:
type: object
description: Additional options for string fields
properties:
length:
type: integer
description: Maximum length of the string field
pattern:
type: string
description: Regex pattern that the string field value must match
values:
type: array
description: List of allowed values for enum fields
items:
type: string
valuesRestricted:
type: boolean
description: Indicates if the field value must be limited to what's in Values
defaultValue:
type: string
description: Default value for the field
UpsertMetadataRequest:
type: object
description: Request payload for upserting metadata (fields only)
properties:
groupRef:
type: string
description: The ID that your app uses to identify the group of users for this request.
example: group-123
fields:
type: object
description: Maps object names to field definitions
additionalProperties:
type: array
items:
$ref: '#/components/schemas/FieldDefinition'
required:
- groupRef
- fields
FieldDefinition:
type: object
description: Field definition for creating or updating custom fields
properties:
fieldName:
type: string
description: The identifier of the field
example: My_Custom_Field
displayName:
type: string
description: The human-readable name of the field
example: My Custom Field
description:
type: string
description: Optional description of the field
valueType:
type: string
description: The data type of the field. Valid values are string, boolean, date, datetime, singleSelect, multiSelect, int, float, reference
example: string
required:
type: boolean
description: Indicates if the field is required
unique:
type: boolean
description: Indicates if the field must be unique across all records
indexed:
type: boolean
description: Indicates if the field should be indexed for faster search
stringOptions:
$ref: '#/components/schemas/StringFieldOptions'
numericOptions:
$ref: '#/components/schemas/NumericFieldOptions'
association:
$ref: '#/components/schemas/AssociationDefinition'
required:
- fieldName
- displayName
- valueType
NumericFieldOptions:
type: object
description: Additional options for numeric fields
properties:
precision:
type: integer
description: Total number of digits (for decimal types)
scale:
type: integer
description: Number of digits to the right of the decimal point (for decimal types)
min:
type: number
description: Minimum value for numeric fields
max:
type: number
description: Maximum value for numeric fields
defaultValue:
type: number
description: Default value for the field
securitySchemes:
APIKeyHeader:
type: apiKey
name: X-Api-Key
in: header
Bearer:
type: http
scheme: bearer
bearerFormat: JWT