Create Data Object

curl --request POST \
  --url https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "[Field Name]": {}
}
'

import requests

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

payload = { "[Field Name]": {} }
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({'[Field Name]': {}})
};

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 => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '[Field Name]' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"[Field Name]\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"[Field Name]\": {}\n}")
  .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::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"[Field Name]\": {}\n}"

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

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

POST

businessareas

{businessAreaId}

schemas

{schemaId}

datasets

{datasetId}

dataobjects

Create Data Object

curl --request POST \
  --url https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "[Field Name]": {}
}
'

import requests

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

payload = { "[Field Name]": {} }
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({'[Field Name]': {}})
};

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 => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '[Field Name]' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"[Field Name]\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pretectum.io/v1/businessareas/{businessAreaId}/schemas/{schemaId}/datasets/{datasetId}/dataobjects")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"[Field Name]\": {}\n}")
  .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::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"[Field Name]\": {}\n}"

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

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

The Create Data Object endpoint allows you to add new records to a dataset. The data object structure is determined by the schema definition, and the API validates field values according to schema rules.

Prerequisites

A Pretectum API key (see API Keys)
Permission to create 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 that defines the data structure. You can obtain this from the List Schemas endpoint.

string

required

The unique identifier of the dataset where the data object will be created. You can obtain this from the List Datasets endpoint.

Headers

string

required

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

string

required

Must be application/json.

string

default:"application/json"

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

Request Body

The request body should be a JSON object with field names as keys and their values. Field names must match the schema field names exactly.

varies

required

Dynamic fields based on the schema definition. Use the field names as defined in the schema. Values should be formatted according to the field’s data type:

string: Plain text values
integer: Whole numbers
float: Decimal numbers
boolean: true or false
date: Date string in the format defined by the schema (e.g., “MM/DD/YYYY”)
datetime: DateTime string in the format defined by the schema
time: Time string in the format defined by the schema
email: Valid email address
url: Valid URL
phone: Phone number string
picklist: Value from the predefined list

Example Requests

curl -X POST "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234/datasets/20240925152201042a1b2c3d4e5f6789012345678901234/dataobjects" \
  -H "Authorization: pre_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "First Name": "John",
    "Last Name": "Smith",
    "Email": "john.smith@example.com",
    "Phone": "+1 555-123-4567",
    "Date of Birth": "01/15/1985",
    "Status": "Active"
  }'

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

async function createDataObject(businessAreaId, schemaId, datasetId, data) {
  const response = await fetch(
    `https://api.pretectum.io/v1/businessareas/${businessAreaId}/schemas/${schemaId}/datasets/${datasetId}/dataobjects`,
    {
      method: 'POST',
      headers: {
        'Authorization': apiKey,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(data)
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to create data object: ${response.statusText}`);
  }

  return response.json();
}

const newCustomer = {
  'First Name': 'John',
  'Last Name': 'Smith',
  'Email': 'john.smith@example.com',
  'Phone': '+1 555-123-4567',
  'Date of Birth': '01/15/1985',
  'Status': 'Active'
};

const created = await createDataObject(businessAreaId, schemaId, datasetId, newCustomer);
console.log(`Created data object with ID: ${created._dataObjectId}`);

import requests

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

def create_data_object(business_area_id, schema_id, dataset_id, data):
    response = requests.post(
        f'https://api.pretectum.io/v1/businessareas/{business_area_id}/schemas/{schema_id}/datasets/{dataset_id}/dataobjects',
        json=data,
        headers={
            'Authorization': api_key,
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        }
    )
    response.raise_for_status()
    return response.json()

new_customer = {
    'First Name': 'John',
    'Last Name': 'Smith',
    'Email': 'john.smith@example.com',
    'Phone': '+1 555-123-4567',
    'Date of Birth': '01/15/1985',
    'Status': 'Active'
}

created = create_data_object(business_area_id, schema_id, dataset_id, new_customer)
print(f"Created data object with ID: {created['_dataObjectId']}")

Response

A successful request returns the created data object with system-generated fields.

string

required

The unique identifier generated for the new data object.

integer

required

The version number of the data object. A newly created object starts at version 0; each successful update increments it by one. Send the current value as _version when updating.

array

required

An array of validation errors. If the data doesn’t conform to schema validation rules, errors will be listed here. The data object is still created, but flagged with errors.

Show Error object properties

string

The name of the field that has the validation error.

string

Description of the validation error.

varies

The field values as stored in the system. These may be transformed based on schema rules (e.g., date formatting).

Example Response

{
  "_dataObjectId": "20240601120000123f1a2b3c4d5e6789012345678901234",
  "_version": 0,
  "_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"
}

Response with Validation Errors

If the data doesn’t conform to schema rules, the object is created but flagged with errors:

{
  "_dataObjectId": "20240601120000123f1a2b3c4d5e6789012345678901234",
  "_version": 0,
  "_errors": [
    {
      "name": "Email",
      "errors": "Invalid email format"
    },
    {
      "name": "Date of Birth",
      "errors": "Date format does not match expected format MM/DD/YYYY"
    }
  ],
  "First Name": "John",
  "Last Name": "Smith",
  "Email": "invalid-email",
  "Phone": "+1 555-123-4567",
  "Date of Birth": "1985-01-15",
  "Status": "Active"
}

Error Responses

Status Code	Description
`400 Bad Request`	Invalid request body or malformed JSON; a missing primary key value when the schema has one (`PRIMARY_KEY_REQUIRED`); or a primary key value already used by another record in the dataset (`DUPLICATE_PRIMARY_KEY`).
`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 create 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.

Validation

The API validates field values based on the schema definition:

Required fields: Fields marked as required in the schema must have a value.
Data types: Values must match the expected data type (e.g., integers for integer fields).
Format validation: Emails, URLs, phones, and dates are validated against their expected formats.
Picklist values: Values must be from the predefined list if the field is a picklist.

Data objects with validation errors are still created but flagged in the _errors array. This allows you to import data and fix validation issues later.

Best Practices

Validate before sending: Validate data on the client side before making API calls to reduce errors.
Use correct field names: Field names are case-sensitive and must match the schema exactly.
Handle errors gracefully: Check the _errors array in the response to identify and report validation issues.
Store the ID: Save the _dataObjectId for future updates or deletions.
Batch imports: For large data imports, consider using the batch import feature instead of individual API calls.

List Data Objects

Retrieve records from 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

Get Schema Details

View schema field definitions

​Prerequisites

​Authentication

​Request

​Path Parameters

​Headers

​Request Body

​Example Requests

​Response

​Example Response

​Response with Validation Errors

​Error Responses

​Validation

​Best Practices

​Related Endpoints

List Data Objects

Update Data Object

Delete Data Object

Get Data Object by Primary Key

Get Schema Details

Prerequisites

Authentication

Request

Path Parameters

Headers

Request Body

Example Requests

Response

Example Response

Response with Validation Errors

Error Responses

Validation

Best Practices

Related Endpoints