PlatformXeDocs
Get API Key

Service Processors

Step-by-step guide for configuring PlatformXe service processors via API and Terraform.

This guide walks through configuring service processors for each of PlatformXe's seven configurable services. Processors let you customize runtime behaviour per tenant -- things like OCR confidence thresholds, messaging defaults, storage moderation, and export formats.

Prerequisites

  • A PlatformXe API key with {service}:manage scope for each service you want to configure
  • For Terraform: the PlatformXe Terraform provider configured (see Terraform Provider Guide)

Understanding the pattern

Every processor follows the same API pattern:

GET  /api/v1/{service}/processor   -- read current config
PUT  /api/v1/{service}/processor   -- update config (shallow merge)

The PUT endpoint performs a shallow merge: fields you include are updated, fields you omit are left unchanged. You never need to send the full config -- just the fields you want to change.

Step 1: Read current configuration

Before making changes, read the current processor to understand what defaults are in place.

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

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

// Read all seven processors
const ocr = await px.ocr.getProcessor();
const messaging = await px.messaging.getProcessor();
const storage = await px.storage.getProcessor();
const exports = await px.exports.getProcessor();
const qr = await px.qr.getProcessor();

Step 2: Configure each service

OCR -- Adjust confidence and languages

If your users submit documents in multiple languages or with varying quality, adjust the confidence threshold and language list.

await px.ocr.updateProcessor({
  config: {
    confidenceThreshold: 0.75,
    supportedDocumentTypes: ['passport', 'drivers_license', 'national_id', 'nin_slip'],
    languages: ['en', 'fr', 'ha', 'yo'],
  },
});

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.75,
      "supportedDocumentTypes": ["passport", "drivers_license", "national_id", "nin_slip"],
      "languages": ["en", "fr", "ha", "yo"]
    }
  }'

Messaging -- Set from name and enable WhatsApp

Configure default sender information and enable additional channels.

await px.messaging.updateProcessor({
  config: {
    email: {
      fromName: 'Acme Platform',
      replyTo: 'support@acme.com',
    },
    sms: {
      defaultRegionCode: 'NG',
    },
    whatsapp: {
      enabled: true,
    },
  },
});

Storage -- Enable auto-reject and set size limits

Tighten content moderation and adjust file size limits based on your application's needs.

await px.storage.updateProcessor({
  config: {
    moderation: {
      enabled: true,
      autoReject: true,
      blockedMimeTypes: ['application/x-executable'],
    },
    limits: {
      maxImageSizeMb: 5,
      maxDocumentSizeMb: 50,
      maxVideoSizeMb: 200,
    },
  },
});

Exports -- Restrict to CSV and extend retention

await px.exports.updateProcessor({
  config: {
    allowedFormats: ['csv'],
    maxRowsPerExport: 50000,
    retentionDays: 90,
  },
});

QR -- Set default format and batch limit

await px.qr.updateProcessor({
  config: {
    defaultSize: 500,
    defaultFormat: 'svg',
    maxBatchSize: 50,
  },
});

Identity -- Configure verification methods

await px.identity.updateProcessor({
  config: {
    verificationMethods: ['bvn', 'nin'],
    consentRequired: true,
    ndprCompliance: true,
  },
});

Step 3: Configure with Terraform

For infrastructure-as-code workflows, use the PlatformXe Terraform provider to manage processor configuration.

resource "platformxe_processor" "ocr" {
  service = "ocr"
  enabled = true
  config = jsonencode({
    confidenceThreshold     = 0.80
    supportedDocumentTypes  = ["passport", "drivers_license", "national_id"]
    languages               = ["en", "fr"]
  })
}

resource "platformxe_processor" "messaging" {
  service = "messaging"
  enabled = true
  config = jsonencode({
    email = {
      fromName = "Acme Platform"
      replyTo  = "support@acme.com"
    }
    sms = {
      defaultRegionCode = "NG"
    }
    whatsapp = {
      enabled = true
    }
  })
}

resource "platformxe_processor" "storage" {
  service = "storage"
  enabled = true
  config = jsonencode({
    provider = "cloudinary"
    moderation = {
      enabled      = true
      autoReject   = true
      blockedMimeTypes = ["application/x-executable"]
    }
    limits = {
      maxImageSizeMb    = 5
      maxDocumentSizeMb = 50
      maxVideoSizeMb    = 200
    }
  })
}

resource "platformxe_processor" "exports" {
  service = "exports"
  enabled = true
  config = jsonencode({
    allowedFormats    = ["csv", "json"]
    maxRowsPerExport  = 100000
    retentionDays     = 90
  })
}

resource "platformxe_processor" "qr" {
  service = "qr"
  enabled = true
  config = jsonencode({
    defaultSize   = 500
    defaultFormat = "svg"
    maxBatchSize  = 50
  })
}

resource "platformxe_processor" "identity" {
  service = "identity"
  enabled = true
  config = jsonencode({
    verificationMethods = ["bvn", "nin", "passport"]
    consentRequired     = true
    ndprCompliance      = true
  })
}

Apply the configuration:

terraform plan
terraform apply

Step 4: Verify configuration

After updating, read the processors to confirm your changes took effect.

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

const messaging = await px.messaging.getProcessor();
console.log(messaging.config.whatsapp.enabled);
// true

Disabling a service

Set enabled: false to disable a service entirely. Requests to a disabled service return a SERVICE_DISABLED error.

// Disable QR generation
await px.qr.updateProcessor({ enabled: false });

resource "platformxe_processor" "qr" {
  service = "qr"
  enabled = false
  config  = jsonencode({})
}

Python examples

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

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

# Update storage limits
px.storage.update_processor({
    "config": {
        "limits": {
            "maxImageSizeMb": 5,
            "maxDocumentSizeMb": 50
        }
    }
})

# Disable exports
px.exports.update_processor({"enabled": False})

Configuration reference

For the full field reference for each service, see the individual processor pages: