Quickstart

This guide shows the fastest path to connect an application to PredictaID using the public client-credential APIs.

What You Need

Before coding, ask your PredictaID administrator for:

• clientId
• clientSecret
• API base URL for your environment
• Webhook signing secret
• The list of events your application should receive

Keep clientSecret and the webhook secret on your server. Do not ship them in browsers, mobile apps, logs, analytics, or client-side configuration.

1. Fetch Public App Configuration

Use the Client ID to load branding and public metadata for hosted flows or embedded experiences.

GET /client-apps/public/{clientId}

This endpoint does not require a secret.

{
  "name": "My App",
  "publicName": "My App Verification",
  "branding": {
    "logoUrl": "https://example.com/logo.png",
    "primaryColor": "#1f4ed8"
  },
  "clientId": "client_abc123"
}

2. Authenticate Server Requests

Public integration APIs use client credentials in HTTP headers.

x-client-id: client_abc123
x-client-secret: your_client_secret
Content-Type: application/json

Use these headers from your backend only.

3. Send a KYT Transaction

For new transaction-monitoring integrations, use the KYT ingest endpoint.

POST /kyt/transactions/ingest

{
  "transactionId": "order_100045",
  "externalCustomerId": "customer_789",
  "cpfCnpj": "***.014.426-**",
  "type": "PIX_TRANSFER",
  "channel": "MOBILE_APP",
  "amount": 1250.75,
  "currency": "BRL",
  "occurredAt": "2026-05-06T13:30:00.000Z",
  "origin": {
    "name": "Origin Customer",
    "cpfCnpj": "***.014.426-**",
    "accountReference": "acct_origin_001",
    "country": "BR"
  },
  "destination": {
    "name": "Destination Customer",
    "cpfCnpj": "***.000.000-**",
    "accountReference": "acct_dest_001",
    "country": "BR"
  },
  "metadata": {
    "deviceId": "device_123",
    "ipAddress": "203.0.113.10"
  }
}

A new transaction returns 202 Accepted. Re-sending the same transaction may return 200 OK with duplicate information so your integration can retry safely.

4. Listen for Webhooks

PredictaID sends asynchronous lifecycle and KYT events to your configured webhook URL.

At minimum, subscribe to:

• kyt.transaction.queued
• kyt.transaction.pipeline.completed
• kyt.transaction.dead_lettered
• session.created
• session.completed
• customer.identified

Verify X-PredictAid-Signature before processing the event. See Webhooks and Webhook Events Reference.

5. Route Review Outcomes

Some outcomes are automatic, but compliance-sensitive cases can require human review. Your integration should treat these states carefully:

• REVIEW: a compliance analyst must review the customer, transaction, or evidence.
• PEP or restrictive-list match: review is mandatory until confirmed, dismissed as false positive, or escalated.
• Partial or missing score composition: the score is informational only and is not defensible for approval.
• Missing audit trail: regulatory decisions and audit-ready exports are blocked until the trail is repaired.

See Compliance Workbench for the operational meaning of these states.

Production Checklist

• Store credentials in a secret manager.
• Use HTTPS for all API and webhook traffic.
• Send stable transactionId values for idempotent retries.
• Send x-request-id and x-correlation-id when available.
• Verify webhook signatures using the raw JSON body.
• Process webhooks idempotently by event ID.
• Mask CPF/CNPJ and personal identifiers in logs.
• Confirm with your PredictaID administrator which dashboard actions are enabled for your tenant.