List Business Areas

curl --request GET \
  --url https://api.pretectum.io/v1/my/businessareas \
  --header 'Authorization: <authorization>'

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

fetch('https://api.pretectum.io/v1/my/businessareas', 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/my/businessareas",
  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/my/businessareas"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.pretectum.io/v1/my/businessareas")

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": [
    {
      "businessAreaId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "active": true,
      "createdBy": "<string>",
      "updatedBy": "<string>",
      "createdDate": "<string>",
      "updatedDate": "<string>",
      "version": 123
    }
  ],
  "nextPageKey": "<string>"
}

GET

businessareas

List Business Areas

curl --request GET \
  --url https://api.pretectum.io/v1/my/businessareas \
  --header 'Authorization: <authorization>'

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

fetch('https://api.pretectum.io/v1/my/businessareas', 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/my/businessareas",
  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/my/businessareas"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.pretectum.io/v1/my/businessareas")

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": [
    {
      "businessAreaId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "active": true,
      "createdBy": "<string>",
      "updatedBy": "<string>",
      "createdDate": "<string>",
      "updatedDate": "<string>",
      "version": 123
    }
  ],
  "nextPageKey": "<string>"
}

The List Business Areas endpoint returns the business areas that your API key has been granted access to. Business areas are the top-level organizational units in Pretectum that categorize your master data. Results are paged, like the other list endpoints.

Prerequisites

A Pretectum API key (see API Keys)
Permission to access business areas in your tenant

Authentication

Include your API key in the Authorization header.

Authorization: pre_your_api_key

Request

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

curl -X GET "https://api.pretectum.io/v1/my/businessareas" \
  -H "Authorization: pre_your_api_key" \
  -H "Accept: application/json"

const apiKey = 'pre_your_api_key';

const response = await fetch('https://api.pretectum.io/v1/my/businessareas', {
  headers: {
    'Authorization': apiKey,
    'Accept': 'application/json'
  }
});

const page = await response.json();
console.log(`Found ${page.items.length} business areas`);
page.items.forEach(area => {
  console.log(`- ${area.name}: ${area.description}`);
});
if (page.nextPageKey) {
  console.log('More business areas are available: pass nextPageKey as pageKey');
}

import requests

api_key = 'pre_your_api_key'

response = requests.get(
    'https://api.pretectum.io/v1/my/businessareas',
    headers={
        'Authorization': api_key,
        'Accept': 'application/json'
    }
)

page = response.json()
business_areas = page['items']
print(f"Found {len(business_areas)} business areas")
for area in business_areas:
    print(f"- {area['name']}: {area['description']}")
if page.get('nextPageKey'):
    print('More business areas are available: pass nextPageKey as pageKey')

Response

A successful request returns an object containing an array of business areas and pagination information.

array

required

An array of business area objects your API key has access to.

Show Business area object properties

string

The unique identifier for the business area. Use this ID when referencing the business area in other API calls.

string

The display name of the business area. This is the human-readable name you can use in the businessArea filter parameter when searching data objects.

string

A description of the business area explaining its purpose and the type of data it contains.

boolean

Indicates whether the business area is currently active. Inactive business areas may still contain data but are typically not used for new data entry.

string

The username or identifier of the user who created the business area.

string

The username or identifier of the user who last modified the business area.

string

The ISO 8601 timestamp when the business area was created.

string

The ISO 8601 timestamp when the business area was last modified.

integer

The version number of the business area record. This increments each time the business area is modified.

string

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

Example Response

{
  "items": [
    {
      "businessAreaId": "20240115103000123a1b2c3d4e5f6789012345678901234",
      "name": "Customer",
      "description": "Customer master data including individuals and businesses",
      "active": true,
      "createdBy": "admin",
      "updatedBy": "admin",
      "createdDate": "2024-01-15T10:30:00Z",
      "updatedDate": "2024-06-01T14:22:00Z",
      "version": 3
    },
    {
      "businessAreaId": "20240115103500456b2c3d4e5f67890123456789012345",
      "name": "Product",
      "description": "Product catalog and inventory master data",
      "active": true,
      "createdBy": "admin",
      "updatedBy": "product_manager",
      "createdDate": "2024-01-15T10:35:00Z",
      "updatedDate": "2024-08-15T09:45:00Z",
      "version": 5
    },
    {
      "businessAreaId": "20240201080000789c3d4e5f678901234567890123456",
      "name": "Supplier",
      "description": "Supplier and vendor master data",
      "active": true,
      "createdBy": "admin",
      "updatedBy": "procurement_lead",
      "createdDate": "2024-02-01T08:00:00Z",
      "updatedDate": "2024-07-20T16:30:00Z",
      "version": 2
    }
  ]
}

When more business areas are available than fit in one page, the response also carries nextPageKey:

{
  "items": [ "..." ],
  "nextPageKey": "eyJMYXN0RXZhbHVhdGVkS2V5Ijp7ImJ1c2luZXNzQXJlYUlkIjoiMjAyNDAyMDEwODAwMDAuLi4ifX0="
}

Empty Response

If your API key has not been granted access to any business areas, 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 business areas. Contact your tenant administrator.
`500 Internal Server Error`	An unexpected error occurred on the server. Try again later or contact support.

Use Cases

Filtering Search Results

Use the business area names returned by this endpoint to filter your data object searches:

# First, get the list of business areas
curl -X GET "https://api.pretectum.io/v1/my/businessareas" \
  -H "Authorization: pre_your_api_key"

# Then search within a specific business area
curl -X GET "https://api.pretectum.io/v1/dataobjects/search?query=John&businessArea=Customer" \
  -H "Authorization: pre_your_api_key"

Building Dynamic UI

Populate dropdown menus or filter options in your application with the available business areas:

// Fetch business areas for a filter dropdown (first page)
const { items: businessAreas } = await fetch('https://api.pretectum.io/v1/my/businessareas', {
  headers: { 'Authorization': apiKey }
}).then(res => res.json());

// Build dropdown options
const options = businessAreas
  .filter(area => area.active)
  .map(area => ({
    value: area.name,
    label: area.name,
    description: area.description
  }));

Validating Business Area Access

Check if your application has access to a specific business area before performing operations:

def has_access_to_business_area(api_key, business_area_name):
    response = requests.get(
        'https://api.pretectum.io/v1/my/businessareas',
        headers={'Authorization': api_key}
    )
    business_areas = response.json()['items']
    return any(
        area['name'] == business_area_name and area['active']
        for area in business_areas
    )

Best Practices

Cache the results: Business areas change infrequently. Cache the response and refresh periodically rather than calling this endpoint before every search.
Filter by active status: Only show active business areas in user-facing interfaces unless there’s a specific need to display inactive ones.
Use names for search filters: When filtering searches with the businessArea parameter, use the name field value, not the businessAreaId.
Handle empty responses: Your application should gracefully handle cases where no business areas are returned.
Handle pagination: Check for nextPageKey in the response and fetch the next page with pageKey until it is absent.
Refresh on permission changes: If a user’s permissions change, refresh the cached business area list to reflect their new access.

Search Data Objects

Search within business areas

API Keys

Obtain authentication token

Overview

Authentication

Business Areas

Schemas

Datasets

Data Objects

List Business Areas

Prerequisites

Authentication

Request

Query Parameters

Headers

Example Requests

Response

Example Response

Empty Response

Error Responses

Use Cases

Filtering Search Results

Building Dynamic UI

Validating Business Area Access

Best Practices

Search Data Objects

API Keys

​Prerequisites

​Authentication

​Request

​Query Parameters

​Headers

​Example Requests

​Response

​Example Response

​Empty Response

​Error Responses

​Use Cases

​Filtering Search Results

​Building Dynamic UI

​Validating Business Area Access

​Best Practices

​Related Endpoints

Search Data Objects

API Keys

Prerequisites

Authentication

Request

Query Parameters

Headers

Example Requests

Response

Example Response

Empty Response

Error Responses

Use Cases

Filtering Search Results

Building Dynamic UI

Validating Business Area Access

Best Practices

Related Endpoints