Service Processors

Per-tenant runtime configuration for PlatformXe services.

Service processors are per-tenant configuration objects that control how each PlatformXe service behaves at runtime. Every organization receives sensible defaults on creation. You can read and update processor configuration through a consistent API pattern across all seven configurable services.

Configurable services

Service	Slug	What the processor controls
OCR	`ocr`	Confidence threshold, supported document types, languages
PDF	`pdf`	Default template, enabled templates, branding source
QR	`qr`	Default size, output format, batch limits
Messaging	`messaging`	Email/SMS/WhatsApp sub-configs, from name, reply-to
Storage	`storage`	Provider selection, content moderation, file size limits
Exports	`exports`	Allowed formats, row limits, retention period
Identity	`identity`	Verification methods, consent requirements, NDPR compliance

API pattern

Every service follows the same two-endpoint pattern:

GET /api/v1/{service}/processor -- Read the current processor configuration.

PUT /api/v1/{service}/processor -- Update the processor configuration (partial merge).

Scope: {service}:manage

The PUT endpoint performs a shallow merge. Fields you include in the request body are updated; fields you omit are left unchanged.

Processor object

{
  "success": true,
  "data": {
    "id": "proc_abc123",
    "organizationId": "org_xyz",
    "service": "ocr",
    "enabled": true,
    "config": {
      "provider": "azure",
      "confidenceThreshold": 0.85,
      "supportedDocumentTypes": ["passport", "drivers_license", "national_id"],
      "languages": ["en"]
    },
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-04-01T14:30:00.000Z"
  }
}

Field	Type	Description
`id`	`string`	Unique processor record ID
`organizationId`	`string`	Owning organization
`service`	`string`	One of the seven service slugs
`enabled`	`boolean`	Whether the service is active for this tenant
`config`	`object`	Service-specific configuration (see individual pages)
`createdAt`	`string`	ISO 8601 creation timestamp
`updatedAt`	`string`	ISO 8601 last-update timestamp

Default configuration

When a tenant is created, each processor is initialized with defaults. The table below summarizes the key defaults per service.

Service	Enabled	Key defaults
OCR	Yes	Confidence threshold 0.85, document types: passport, drivers license, national ID
PDF	Yes	Standard template, branding from organization
QR	Yes	300px, PNG format, batch limit 100
Messaging	Yes	Email enabled, SMS enabled, WhatsApp disabled
Storage	Yes	Moderation enabled (manual review), 10 MB images / 25 MB docs / 100 MB video
Exports	Yes	CSV and JSON, 100k row limit, 30-day retention
Identity	Yes	BVN + NIN + passport verification, consent required, NDPR compliant

How processor config affects runtime

When a service processes a request, it loads the tenant's processor configuration and applies it:

OCR rejects extractions below the configured confidenceThreshold and only processes document types in supportedDocumentTypes.
Messaging uses the preferredProviders list to determine failover order and applies fromName / replyTo as defaults when not supplied per-request.
Storage enforces limits.maxImageSizeMb on uploads and runs moderation checks when moderation.enabled is true.
Exports caps output at maxRowsPerExport rows and auto-deletes completed exports after retentionDays.

Examples

Read processor configuration

curl

curl https://api.platformxe.com/api/v1/ocr/processor \
  -H "x-api-key: pxk_live_your_api_key_here"

TypeScript SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const processor = await px.ocr.getProcessor();
console.log(processor.config.confidenceThreshold);
// 0.85

Python SDK

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

processor = px.ocr.get_processor()
print(processor["config"]["confidenceThreshold"])
# 0.85

Go SDK

import platformxe "github.com/calderax/platformxe-go"

client := platformxe.NewClient("pxk_live_your_api_key_here")
processor, err := client.Processors.Get("ocr")

Update processor configuration

curl

curl -X PUT https://api.platformxe.com/api/v1/ocr/processor \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "config": {
      "confidenceThreshold": 0.90,
      "languages": ["en", "fr"]
    }
  }'

TypeScript SDK

await px.ocr.updateProcessor({
  config: {
    confidenceThreshold: 0.90,
    languages: ['en', 'fr'],
  },
});

Python SDK

px.ocr.update_processor({
    "config": {
        "confidenceThreshold": 0.90,
        "languages": ["en", "fr"]
    }
})

Disable a service

curl -X PUT https://api.platformxe.com/api/v1/qr/processor \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{ "enabled": false }'

When a service is disabled, API calls to that service return a SERVICE_DISABLED error.

Error responses

Code	Description
`FORBIDDEN`	API key does not have the `{service}:manage` scope
`NOT_FOUND`	No processor exists for this service (should not occur -- processors are auto-created)
`BAD_REQUEST`	Invalid config structure for the service
`RATE_LIMITED`	Rate limit exceeded