Skip to main content
GET
Get Data Object by Primary Key
The Get Data Object by Primary Key endpoint returns one record from a dataset, looked up by the value of the field the schema marks as its primary key. It is the direct way to fetch a record when you know its business identifier (a customer number, a SKU, an account code) rather than its _dataObjectId, and the cheapest way to check whether a record already exists before creating it.

Prerequisites

Authentication

Include your API key in the Authorization header.

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 to look in. Primary key values are unique within a dataset, not across datasets. You can obtain this from the List Datasets endpoint.
string
required
The value of the primary key field, exactly as stored. Matching is case-sensitive. URL-encode the value if it contains spaces or reserved characters (CUST 001 becomes CUST%20001).

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

Response

A successful request returns the data object in the same shape as List Data Objects: the schema’s fields keyed by their display names, plus the system metadata fields.
string
required
The unique identifier of the data object. Use it with Update Data Object and Delete Data Object.
integer
required
The current version of the data object. Send this value as _version when updating the object; the update is rejected if the object has changed since.
array
required
Validation errors recorded on the data object. Empty when every value passed validation.
varies
The field values, keyed by the schema’s field display names. Date, time and datetime values are formatted according to the schema’s field configuration. Attachment-type fields (image, document, video, attachment) are returned with time-limited download URLs.

Example Response

Not Found

When no record in the dataset has that primary key value, the response is 404 Not Found with an empty body. The same response is returned when the schema has no primary key field, and for a record that has been deleted: deleting a record releases its primary key value, so the value can be used again by a new record.

Error Responses

How the Lookup Works

Pretectum enforces primary key uniqueness within a dataset: when a record is created or its primary key value is changed, the value is reserved in the dataset’s key index, and a second record with the same value is rejected with DUPLICATE_PRIMARY_KEY. This endpoint reads that index, so it is a single, exact lookup regardless of how many records the dataset holds.
Leading and trailing whitespace is trimmed from primary key values both when a record is written and when one is looked up, so " CUST-000123 " and "CUST-000123" refer to the same record. Matching is otherwise exact and case-sensitive, so cust-000123 does not.

Use Cases

Upsert: Create or Update by Business Key

Look a record up by its business identifier and create it if missing, or update it with the version you just read:

Fetching the Current Version Before an Update

An update needs the record’s current _version. When you know the business key, this endpoint is cheaper than paging through List Data Objects to find the record:

Best Practices

  1. Treat 404 as “does not exist”: It is the normal answer for a key that has not been used yet, not a failure. Check the ids only if every lookup returns 404.
  2. URL-encode the value: Key values with spaces, slashes or other reserved characters must be encoded in the path.
  3. Use the returned _version immediately: Another writer may change the record between your lookup and your update. On DATA_OBJECT_VERSION_CONFLICT, look the record up again and retry.
  4. Prefer this endpoint to search for exact lookups: Search Data Objects is for finding records by content; this endpoint is for fetching a known record.

List Data Objects

Page through every record in a dataset

Create Data Object

Add a record when the lookup returns 404

Update Data Object

Modify the record using the returned version

Get Schema Details

Find which field is the primary key