# Retrieve a custom object definition

Retrieves the custom object definition by type for the given tenant.

Endpoint: GET /objects/definitions/default/{object}
Version: 2026-02-20
Security: bearerAuth

## Header parameters:

  - `Accept-Encoding` (string)
    Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. 

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

  - `Content-Encoding` (string)
    Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

  - `Zuora-Entity-Ids` (string)
    An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

  - `Zuora-Org-Ids` (string)
    Comma separated IDs. If you have Zuora Multi-Org enabled, 
you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs.

  - `Zuora-Version` (string)
    API version that determines the response schema. The default version is used if this parameter is not included. Specify Zuora-Version in the request header if you expect a specific response schema.

## Path parameters:

  - `object` (string, required)
    Specifies the custom object's API name as object. It is case-sensitive.

## Response 200 fields (application/json):

  - `CreatedById` (string)
    The creator's Id
    Example: "7b39d73f-22e6-404a-b8e7-894f7620e91c"

  - `CreatedDate` (string)
    The creation time of the custom object definition in date-time format.
    Example: "2019-09-29T06:45:23.378Z"

  - `Id` (string)
    The unique Id of the custom object definition
    Example: "df7f10f9-4ec9-4389-a9eb-a6a3d549bb61"

  - `UpdatedById` (string)
    The modifier's Id
    Example: "7b39d73f-22e6-404a-b8e7-894f7620e91c"

  - `UpdatedDate` (string)
    The update time of the custom object definition in date-time format.
    Example: "2019-09-29T06:45:23.378Z"

  - `schema` (object)
    The schema of the custom object definition
    Example: {"filterable":["last_name__c","email__c"],"label":"Personal Profile","object":"person","properties":{"CreatedById":{"format":"uuid","label":"CreatedById","origin":"system","type":"string"},"CreatedDate":{"format":"date-time","label":"CreatedDate","origin":"system","type":"string"},"Id":{"format":"uuid","label":"Id","origin":"system","type":"string"},"UpdatedById":{"format":"uuid","label":"UpdatedById","origin":"system","type":"string"},"UpdatedDate":{"format":"date-time","label":"UpdatedDate","origin":"system","type":"string"},"age__c":{"description":"Age in years","minimum":0,"origin":"custom","type":"integer"},"email__c":{"format":"email","maxLength":128,"origin":"custom","type":"string"},"home_address__c":{"format":"uuid","origin":"custom","type":"string"},"last_name__c":{"maxLength":128,"origin":"custom","type":"string"},"marital_status__c":{"default":"Unknown","enum":["Single","Married","Unknown"],"origin":"custom","type":"string"},"work_address__c":{"format":"uuid","origin":"custom","type":"string"}},"relationships":[{"cardinality":"manyToOne","fields":{"home_address__c":"Id"},"namespace":"default","object":"address","recordConstraints":{"create":{"enforceValidMapping":false}}},{"cardinality":"manyToOne","fields":{"work_address__c":"Id"},"namespace":"default","object":"address","recordConstraints":{"create":{"enforceValidMapping":false}}},{"cardinality":"oneToMany","fields":{"Id":"person_id__c"},"namespace":"default","object":"car","recordConstraints":{"create":{"enforceValidMapping":false}}},{"cardinality":"oneToMany","fields":{"Id":"person_id__c"},"namespace":"default","object":"device","recordConstraints":{"create":{"enforceValidMapping":false}}}],"required":["last_name__c","marital_status__c"],"type":"object"}

  - `schema.auditable` (array)
    The set of fields which Audit Trail tracks and records changes of.

  - `schema.enableCreateRecordAuditing` (boolean)
    Indicates whether to audit the creation of custom object records of this custom object definition.

  - `schema.enableDeleteRecordAuditing` (boolean)
    Indicates whether to audit the deletion of custom object records of this custom object definition.

  - `schema.filterable` (array)
    The set of fields that are allowed to be queried on. Queries on non-filterable fields will be rejected. You can not change a non-filterable field to filterable.
    Example: ["last_name__c","email__c"]

  - `schema.label` (string)
    A label for the custom object
    Example: "Personal Profile"

  - `schema.object` (string)
    The API name of the custom object
    Example: "person"

  - `schema.properties` (object)
    The definitions of all the fields in the custom object definition

  - `schema.properties.CreatedById` (object)
    The CreatedById field definition

  - `schema.properties.CreatedById.format` (string)
    The field data format
    Enum: "uuid"

  - `schema.properties.CreatedById.label` (string)
    The UI name of the field

  - `schema.properties.CreatedById.origin` (string)
    Specifies whether the field is a system field or a custom field
    Enum: "system"

  - `schema.properties.CreatedById.type` (string)
    The field data type
    Enum: "string"

  - `schema.properties.CreatedDate` (object)
    The CreatedDate field definition

  - `schema.properties.CreatedDate.origin` (string)
    Specifies the field is a system field
    Enum: "system"

  - `schema.properties.Id` (object)
    The Id field definition

  - `schema.properties.UpdatedById` (object)
    The UpdatedById field definition

  - `schema.properties.UpdatedDate` (object)
    The UpdatedDate field definition

  - `schema.relationships` (array)
    An array of relationships with Zuora objects or other custom objects
    Example: [{"cardinality":"manyToOne","fields":{"home_address__c":"Id"},"namespace":"default","object":"address","recordConstraints":{"create":{"enforceValidMapping":false}}},{"cardinality":"manyToOne","fields":{"work_address__c":"Id"},"namespace":"default","object":"address","recordConstraints":{"create":{"enforceValidMapping":false}}},{"cardinality":"oneToMany","fields":{"Id":"person_id__c"},"namespace":"default","object":"car","recordConstraints":{"create":{"enforceValidMapping":false}}},{"cardinality":"oneToMany","fields":{"Id":"person_id__c"},"namespace":"default","object":"device","recordConstraints":{"create":{"enforceValidMapping":false}}}]

  - `schema.relationships.cardinality` (string)
    The cardinality of the relationship from this object to another object.

A manyToOne relationship means this object is the child object (the "many" side), and the referenced object (the "one" side) is the parent.

A oneToMany relationship means this object is the parent object (the "one" side), and the referenced object (the "many" side) is the child.
    Enum: "manyToOne", "oneToMany"

  - `schema.relationships.fields` (object)
    Field mappings in the form of `: `.

  - `schema.relationships.namespace` (string)
    The namespace where the related object is located

  - `schema.relationships.object` (string)
    The API name of the related object

  - `schema.relationships.recordConstraints` (object)
    Specifies contraints to apply to custom object records.

  - `schema.relationships.recordConstraints.create` (object)

  - `schema.relationships.recordConstraints.create.enforceValidMapping` (boolean)
    Specifies whether Zuora validates the values of mapped fields
in custom object records.

  - `schema.required` (array)
    The required fields of the custom object definition. You can change required fields to optional. However, you can only change optional fields to required on the custom objects with no records.
    Example: ["last_name__c","marital_status__c"]

  - `schema.type` (string)
    The custom object definition type. Can only be object currently.
    Enum: "object"

  - `schema.unique` (array)
    The fields with unique constraints.

  - `type` (string)
    The API name of the custom object
    Example: "person"

## Response 404 fields (application/json):

  - `processId` (string)
    The ID of the process that handles the operation.

  - `reasons` (array)
    The container of the error code and message. This field is available only if the success field is false.

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

  - `requestId` (string)
    Unique identifier of the request.

  - `success` (boolean)
    Indicates whether the call succeeded.