Integration Reference

This page summarizes the public integration surface for client applications.

Environments and Base URL

Your PredictaID administrator provides the base URL for each environment.

https://{api-host}

Use separate Client IDs, Client Secrets, webhook endpoints, and secrets for sandbox, staging, and production.

Authentication Model

Public integration endpoints use client credentials:

x-client-id: client_abc123
x-client-secret: your_client_secret

Operator and dashboard APIs use user authentication and permissions. Do not call operator APIs from external client integrations unless PredictaID explicitly enables that contract for your tenant.

Public Endpoint Matrix

Capability	Endpoint	Auth	Notes
Public app metadata	GET /client-apps/public/{clientId}	No secret	Returns public branding and client metadata.
KYT transaction ingest	POST /kyt/transactions/ingest	Client credentials	Preferred endpoint for new KYT integrations.
Legacy transaction create	POST /transactions	Client credentials	Kept for simpler transaction submissions and older integrations.
Public Flow session data	GET /kyc-sessions/{sessionId}/public	Public session ID	Use only with session IDs generated by PredictaID. Treat session links as sensitive.
Complete Flow session	POST /kyc-sessions/{sessionId}/complete	Public session ID	Used by hosted or embedded verification experiences.
Upload session artifact	POST /kyc-sessions/{sessionId}/upload	Public session ID	Multipart upload for artifacts collected during a Flow session.
Webhook delivery	Your HTTPS endpoint	HMAC signature	PredictaID calls your endpoint asynchronously.

Request Correlation

For server-to-server requests, send these headers when possible:

x-request-id: req_01HX...
x-correlation-id: corr_01HX...

PredictaID uses them to connect ingestion, processing, review, and webhook events. If omitted, the platform can generate internal identifiers, but client-provided values make support investigations faster.

Idempotency

For KYT ingestion, transactionId should be stable and unique in your system.

• First accepted submission returns 202 Accepted.
• A duplicate replay can return 200 OK with duplicate metadata.
• Your application should process both responses as successful receipt.
• Webhook handlers should also be idempotent by id and X-PredictAid-Event-ID.

KYT Transaction Payload

Required fields for POST /kyt/transactions/ingest:

Field	Type	Description
transactionId	string	Stable ID from your system.
type	string	Business transaction type, such as PIX_TRANSFER or CARD_PURCHASE.
channel	string	Source channel, such as WEB, MOBILE_APP, or BACKOFFICE.
amount	number	Positive transaction amount.
currency	string	Currency code, usually BRL.
occurredAt	ISO datetime	When the transaction occurred.
origin	object	Origin participant.
destination	object	Destination participant.

Optional but recommended:

Field	Description
externalCustomerId	Your customer ID.
cpfCnpj	Masked in logs and UI; use only when needed for matching.
descriptionOrPurpose	Business description.
country	Country code.
supportingDocument	Reference to supporting evidence.
metadata	Extra attributes used by rules and investigations.

Participant fields include name, cpfCnpj, accountReference, bankReference, walletReference, country, and metadata.

Response Pattern

Successful ingestion returns a wrapped response.

{
  "data": {
    "transactionId": "order_100045",
    "status": "QUEUED",
    "accepted": true,
    "duplicate": false,
    "requestId": "req_01HX...",
    "correlationId": "corr_01HX..."
  },
  "error": null
}

Processing continues asynchronously. Use webhooks for the final pipeline state and any review workflow.

Error Pattern

Common HTTP responses:

Status	Meaning	Integration action
400	Invalid payload	Fix the request shape or field values.
401	Invalid client credentials	Rotate or correct credentials.
403	App disabled or insufficient scope	Contact your PredictaID administrator.
404	Resource not found	Check IDs and environment.
409	Conflict	Use returned details to reconcile state.
429	Rate limited	Retry with backoff.
5xx	Platform or downstream error	Retry safely when the operation is idempotent.

Webhook Requirements

Your webhook endpoint should:

• Accept POST over HTTPS.
• Read and preserve the raw request body for signature validation.
• Verify X-PredictAid-Signature.
• Process duplicate events idempotently.
• Return a 2xx status only after durable receipt.
• Avoid long processing inside the HTTP request. Queue work internally when possible.

Compliance and Risk Semantics

Do not treat every numeric score as an approval signal.

• A defensible risk result requires score composition, ruleset context, evidence, and audit trail.
• Partial, missing, inconsistent, or unknown composition means the score is informational.
• PEP or restrictive-list matches require review before approval.
• Missing identity, missing required documents, missing audit trail, or open manual cases can block decisions.

The dashboard exposes these states in the Compliance Workbench. See Compliance Workbench.

Sensitive Data Handling

• Mask CPF/CNPJ and tax identifiers in logs and screenshots.
• Restrict raw bureau data to authorized operators.
• Avoid storing full session links in analytics tools.
• Treat public Flow session URLs as sensitive bearer-style links.
• Align retention and deletion processes with your LGPD obligations and contract terms.

Go-Live Checklist

• Credentials separated per environment.
• Webhook signature validation deployed.
• Webhook retries and duplicate handling tested.
• KYT duplicate submission tested.
• Compliance review statuses mapped in your back office.
• Sensitive fields masked in logs and observability tools.
• Support runbook includes request ID, correlation ID, transaction ID, and event ID.