Skip to main content
GET
https://api.pretectum.io
/
v1
/
my
/
businessareas
List Business Areas
curl --request GET \
  --url https://api.pretectum.io/v1/my/businessareas \
  --header 'Authorization: <authorization>'
{
  "response": [
    {
      "businessAreaId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "active": true,
      "createdBy": "<string>",
      "updatedBy": "<string>",
      "createdDate": "<string>",
      "updatedDate": "<string>",
      "version": 123
    }
  ]
}
The List Business Areas endpoint returns all business areas that your application client has been granted access to. Business areas are the top-level organizational units in Pretectum that categorize your master data.

​
Prerequisites

  • Valid access token (see Get Access Token)
  • Permission to access business areas in your tenant

​
Authentication

Include your access token in the Authorization header.
Pass the token directly without the “Bearer” prefix.
Authorization: your_access_token

​
Request

​
Headers

​
Authorization
string
required
Your access token obtained from the /v1/oauth2/token endpoint. Pass the token directly without the “Bearer” prefix.
​
Accept
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: your_access_token" \
  -H "Accept: application/json"

​
Response

A successful request returns an array of business area objects that your application has access to.
​
response
array
required
An array of business area objects.

​
Example Response

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

​
Empty Response

If your application client has not been granted access to any business areas, the response will be an empty array: 
[]

​
Error Responses

Status CodeDescription
401 UnauthorizedInvalid or expired access token. Obtain a new token from /v1/oauth2/token and try again.
403 ForbiddenYour application client does not have permission to access business areas. Contact your tenant administrator.
500 Internal Server ErrorAn 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: your_access_token"

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

​
Building Dynamic UI

Populate dropdown menus or filter options in your application with the available business areas: 
// Fetch business areas for a filter dropdown
const businessAreas = await fetch('https://api.pretectum.io/v1/my/businessareas', {
  headers: { 'Authorization': accessToken }
}).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(access_token, business_area_name):
    response = requests.get(
        'https://api.pretectum.io/v1/my/businessareas',
        headers={'Authorization': access_token}
    )
    business_areas = response.json()
    return any(
        area['name'] == business_area_name and area['active']
        for area in business_areas
    )

​
Best Practices

  1. Cache the results: Business areas change infrequently. Cache the response and refresh periodically rather than calling this endpoint before every search.
  2. Filter by active status: Only show active business areas in user-facing interfaces unless there’s a specific need to display inactive ones.
  3. Use names for search filters: When filtering searches with the businessArea parameter, use the name field value, not the businessAreaId.
  4. Handle empty responses: Your application should gracefully handle cases where no business areas are returned.
  5. 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

Get Access Token

Obtain authentication token