> ## Documentation Index > Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt > Use this file to discover all available pages before exploring further. # Get object metadata via installation > 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']`). ## OpenAPI ````yaml platform get /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/metadata openapi: 3.0.1 info: title: Ampersand public API version: 1.0.0 servers: - url: https://api.withampersand.com/v1 security: - APIKeyHeader: [] - Bearer: [] paths: /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/metadata: get: tags: - Objects & Fields summary: 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']`). 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: 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: title: Field Metadata type: object description: >- Metadata about a field. Please note that different providers have different levels of support for field metadata. Please reach out to support@withampersand.com if need expanded support for a particular provider. required: - fieldName - displayName properties: fieldName: type: string description: The name of the field from the provider API. example: accountid displayName: type: string description: The display name of the field from the provider API. example: Account ID valueType: type: string description: A normalized field type enum: - string - boolean - singleSelect - multiSelect - date - datetime - int - float - reference - other x-go-type-skip-optional-pointer: true providerType: type: string description: Raw field type from the provider API. example: timestamp x-go-type-skip-optional-pointer: true readOnly: type: boolean description: Whether the field is read-only. example: false isCustom: type: boolean description: Whether the field is custom field. example: false isRequired: type: boolean description: >- Whether the field is required when creating a new record. example: false referenceTo: type: array description: >- The list of object types this field references. Only applicable if the providerType is a lookup/reference field. x-go-type-skip-optional-pointer: true items: type: string values: type: array description: >- If the valueType is singleSelect or multiSelect, this is a list of possible values x-go-type-skip-optional-pointer: true items: title: Field Value type: object required: - value - displayValue description: Represents a field value properties: value: type: string description: The internal value used by the system example: outbound displayValue: type: string description: The human-readable display value example: Outbound Campaign 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: title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: Description of the type of problem that occurred status: 400 detail: Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez components: securitySchemes: APIKeyHeader: type: apiKey name: X-Api-Key in: header Bearer: type: http scheme: bearer bearerFormat: JWT ````