List Data Objects

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

import requests

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

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

GET

businessareas

{businessAreaId}

schemas

{schemaId}

datasets

{datasetId}

dataobjects

List Data Objects

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

import requests

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

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects")
  .header("Authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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

A Pretectum API key (see API Keys)
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 API key in the Authorization header.

Authorization: pre_your_api_key

Request

Path Parameters

string

required

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

string

required

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

string

required

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

Query Parameters

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

string

required

Your Pretectum API key. Create one in the Pretectum app under Configuration → API Keys.

string

default:"application/json"

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

Example Requests

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

const apiKey = 'pre_your_api_key';
const businessAreaId = '20240115103000123a1b2c3d4e5f6789012345678901234';
const schemaId = '20240115103000456d1e2f3a4b5c6789012345678901234';
const datasetId = '20240925152201042a1b2c3d4e5f6789012345678901234';

async function getDataObjects(businessAreaId, schemaId, datasetId, pageKey = null) {
  const url = new URL(
    `https://api.pretectum.io/v1/businessareas/${businessAreaId}/schemas/${schemaId}/datasets/${datasetId}/dataobjects`
  );
  if (pageKey) {
    url.searchParams.set('pageKey', pageKey);
  }

  const response = await fetch(url, {
    headers: {
      'Authorization': apiKey,
      'Accept': 'application/json'
    }
  });

  return response.json();
}

const dataObjects = await getDataObjects(businessAreaId, schemaId, datasetId);
console.log(`Retrieved ${dataObjects.items.length} data objects`);
dataObjects.items.forEach(obj => {
  console.log(`- ${obj._dataObjectId}: ${obj['First Name']} ${obj['Last Name']}`);
});

import requests

api_key = 'pre_your_api_key'
business_area_id = '20240115103000123a1b2c3d4e5f6789012345678901234'
schema_id = '20240115103000456d1e2f3a4b5c6789012345678901234'
dataset_id = '20240925152201042a1b2c3d4e5f6789012345678901234'

def get_data_objects(business_area_id, schema_id, dataset_id, page_key=None):
    params = {}
    if page_key:
        params['pageKey'] = page_key

    response = requests.get(
        f'https://api.pretectum.io/v1/businessareas/{business_area_id}/schemas/{schema_id}/datasets/{dataset_id}/dataobjects',
        params=params,
        headers={
            'Authorization': api_key,
            'Accept': 'application/json'
        }
    )
    response.raise_for_status()
    return response.json()

data_objects = get_data_objects(business_area_id, schema_id, dataset_id)
print(f"Retrieved {len(data_objects['items'])} data objects")
for obj in data_objects['items']:
    print(f"- {obj['_dataObjectId']}: {obj.get('First Name', '')} {obj.get('Last Name', '')}")

Response

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

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

string

The unique identifier for the data object.

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.

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

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.

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": "john.smith@example.com",
      "Phone": "+1 555-123-4567",
      "Date of Birth": "01/15/1985",
      "Status": "Active"
    },
    {
      "_dataObjectId": "20240601120100456g2b3c4d5e6f7890123456789012345",
      "_version": 2,
      "_errors": [],
      "First Name": "Jane",
      "Last Name": "Doe",
      "Email": "jane.doe@example.com",
      "Phone": "+1 555-987-6543",
      "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`	The API key is missing, malformed, unknown, inactive, expired or deleted. Check the key in Configuration → API Keys.
`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:

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}`);

def get_all_data_objects(business_area_id, schema_id, dataset_id):
    all_data_objects = []
    page_key = None

    while True:
        response = get_data_objects(business_area_id, schema_id, dataset_id, page_key)
        all_data_objects.extend(response['items'])
        print(f"Retrieved {len(all_data_objects)} data objects so far...")

        page_key = response.get('nextPageKey')
        if not page_key:
            break

    return all_data_objects

all_data_objects = get_all_data_objects(business_area_id, schema_id, dataset_id)
print(f"Total data objects: {len(all_data_objects)}")

Best Practices

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

Create Data Object

Add new records to a dataset

Update Data Object

Modify existing records

Delete Data Object

Remove records from a dataset

Get Data Object by Primary Key

Fetch one record by its primary key value

Search Data Objects

Search across all datasets

​Prerequisites

​Authentication

​Request

​Path Parameters

​Query Parameters

​Headers

​Example Requests

​Response

​Example Response

​Response with Validation Errors

​Empty Response

​Error Responses

​Pagination

​Best Practices

​Related Endpoints

Create Data Object

Update Data Object

Delete Data Object

Get Data Object by Primary Key

Search Data Objects

Prerequisites

Authentication

Request

Path Parameters

Query Parameters

Headers

Example Requests

Response

Example Response

Response with Validation Errors

Empty Response

Error Responses

Pagination

Best Practices

Related Endpoints