Create Data Object

Create a new data object (record) in a specific dataset

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

Create Data Object

cURL

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]": {}
}
'

200

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

• Valid access token (see Get Access Token)
• 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 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 that defines the data structure. You can obtain this from the List Schemas endpoint.

datasetId · 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

Authorization · string · required

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

Content-Type · string · required

Must be application/json.

Accept · 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.

[Field Name] · 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

curl -X POST "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234/datasets/20240925152201042a1b2c3d4e5f6789012345678901234/dataobjects" \
  -H "Authorization: your_access_token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "First Name": "John",
    "Last Name": "Smith",
    "Email": "[e-mail]",
    "Phone": "[phone]",
    "Date of Birth": "01/15/1985",
    "Status": "Active"
  }'

Response

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

_dataObjectId · string · required

The unique identifier generated for the new data object.

_version · integer · required

The version number of the data object. New objects start at version 1.

_errors · 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

name · string

The name of the field that has the validation error.

errors · string

Description of the validation error.

[Field Name] · 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": 1,
  "_errors": [],
  "First Name": "John",
  "Last Name": "Smith",
  "Email": "[e-mail]",
  "Phone": "[phone]",
  "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": 1,
  "_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": "[phone]",
  "Date of Birth": "1985-01-15",
  "Status": "Active"
}

Error Responses

Status Code	Description
400 Bad Request	Invalid request body or malformed JSON. Check your request format.
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 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

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

Related Endpoints

List Data Objects

Retrieve records from a dataset

Update Data Object

Modify existing records

Delete Data Object

Remove records from a dataset

Get Schema Details

View schema field definitions