List Data Objects

Retrieve a paginated list of data objects within a specific dataset

GET https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects

List Data Objects

cURL

curl --request GET \
  --url https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects \
  --header 'Authorization: <authorization>'

200

{
  "items": [
    {
      "_dataObjectId": "<string>",
      "_version": 123,
      "_errors": [
        {}
      ],
      "[Field Name]": {}
    }
  ],
  "nextPageKey": "<string>"
}

The List Data Objects endpoint returns all data objects within a specific dataset. Data objects are the actual records in your master data repository, containing field values that conform to the schema structure.

Prerequisites

• Valid access token (see Get Access Token)
• Permission to access data objects in your tenant
• Valid business area ID (see List Business Areas)
• Valid schema ID (see List Schemas)
• Valid dataset ID (see List Datasets)

Authentication

Include your access token in the Authorization header.

Pass the token directly without the “Bearer” prefix.

Authorization: your_access_token

Request

Path Parameters

businessAreaId · string · required

The unique identifier of the business area. You can obtain this from the List Business Areas endpoint.

schemaId · string · required

The unique identifier of the schema. You can obtain this from the List Schemas endpoint.

datasetId · string · required

The unique identifier of the dataset containing the data objects. You can obtain this from the List Datasets endpoint.

Query Parameters

pageKey · string

A pagination token for retrieving the next page of results. This value is returned in the response as nextPageKey when more results are available.

Headers

Authorization · string · required

Your access token obtained from the /v1/oauth2/token endpoint. Pass the token directly without the “Bearer” prefix.

Accept · string · default: "application/json"

The response content type. Currently only application/json is supported.

Example Requests

cURL

# List all data objects in a dataset
curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234/datasets/20240925152201042a1b2c3d4e5f6789012345678901234/dataobjects" \
  -H "Authorization: your_access_token" \
  -H "Accept: application/json"

# Paginate through data objects
curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234/datasets/20240925152201042a1b2c3d4e5f6789012345678901234/dataobjects?pageKey=eyJMYXN0RXZhbHVhdGVkS2V5Ijp7Li4ufQ" \
  -H "Authorization: your_access_token" \
  -H "Accept: application/json"

Response

A successful request returns an object containing an array of data objects and pagination information.

items · array · required

An array of data objects. Each object contains dynamic fields based on the schema definition, plus system-generated metadata fields.

Show Data object properties

_dataObjectId · string

The unique identifier for the data object.

_version · integer

The version number of the data object. This increments each time the object is updated. Use this value when updating the object to prevent concurrent modification conflicts.

_errors · array

An array of validation errors for the data object. Each error object contains:

• name: The field name that has the error
• errors: Description of the validation error

[Field Name] · varies

Dynamic fields based on the schema definition. Field names match the schema field names (not field IDs). The data type depends on the field configuration in the schema.

nextPageKey · string

A pagination token for retrieving the next page of results. If this field is present, more data objects are available. Pass this value as the pageKey query parameter in your next request.

Example Response

{
  "items": [
    {
      "_dataObjectId": "20240601120000123f1a2b3c4d5e6789012345678901234",
      "_version": 1,
      "_errors": [],
      "First Name": "John",
      "Last Name": "Smith",
      "Email": "[e-mail]",
      "Phone": "[phone]",
      "Date of Birth": "01/15/1985",
      "Status": "Active"
    },
    {
      "_dataObjectId": "20240601120100456g2b3c4d5e6f7890123456789012345",
      "_version": 2,
      "_errors": [],
      "First Name": "Jane",
      "Last Name": "Doe",
      "Email": "[e-mail]",
      "Phone": "[phone]",
      "Date of Birth": "03/22/1990",
      "Status": "Active"
    }
  ],
  "nextPageKey": "eyJMYXN0RXZhbHVhdGVkS2V5Ijp7ImRhdGFPYmplY3RJZCI6IjIwMjQwNjAxMTIwMTAw..."
}

Response with Validation Errors

Data objects may have validation errors if the data doesn’t conform to schema rules:

{
  "items": [
    {
      "_dataObjectId": "20240601120000123f1a2b3c4d5e6789012345678901234",
      "_version": 1,
      "_errors": [
        {
          "name": "Email",
          "errors": "Invalid email format"
        },
        {
          "name": "Phone",
          "errors": "Phone number is required"
        }
      ],
      "First Name": "John",
      "Last Name": "Smith",
      "Email": "invalid-email",
      "Phone": null,
      "Status": "Active"
    }
  ]
}

Empty Response

If the dataset has no data objects, the response will contain an empty items array:

{
  "items": []
}

Error Responses

Status Code	Description
401 Unauthorized	Invalid or expired access token. Obtain a new token from /v1/oauth2/token and try again.
403 Forbidden	Your application client does not have permission to access data objects. Contact your tenant administrator.
404 Not Found	The specified business area, schema, or dataset does not exist, or you do not have access to it.
500 Internal Server Error	An unexpected error occurred on the server. Try again later or contact support.

Pagination

When a dataset contains many data objects, results are paginated. Use the nextPageKey from the response to fetch subsequent pages:

JavaScript

async function getAllDataObjects(businessAreaId, schemaId, datasetId) {
  const allDataObjects = [];
  let pageKey = null;

  do {
    const response = await getDataObjects(businessAreaId, schemaId, datasetId, pageKey);
    allDataObjects.push(...response.items);
    pageKey = response.nextPageKey;
    console.log(`Retrieved ${allDataObjects.length} data objects so far...`);
  } while (pageKey);

  return allDataObjects;
}

const allDataObjects = await getAllDataObjects(businessAreaId, schemaId, datasetId);
console.log(`Total data objects: ${allDataObjects.length}`);

Best Practices

1. Use pagination: Always handle pagination for large datasets. Don’t assume all data will fit in a single response.
2. Cache schema information: Fetch the schema once to understand field names and types, then reuse it when processing data objects.
3. Handle validation errors: Check the _errors array to identify data quality issues that need attention.
4. Use version for updates: Store the _version value if you plan to update the data object later.

Related Endpoints

Create Data Object

Add new records to a dataset

Update Data Object

Modify existing records

Delete Data Object

Remove records from a dataset

Search Data Objects

Search across all datasets