Facade API Integration Guide

This guide is for organizations that integrate with Trua Cloud through the Facade API rather than the candidate collection wizard. Facade-only customers send API requests to Trua Cloud, which mediates the request by translating field names, routing to internal handlers, and returning mapped responses.

How the Facade API Differs from Direct Integration

Authentication

The Facade API uses the same API key infrastructure as the Candidate Progress API:

Include the key in the Authorization header or X-Api-Key header:

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx

or:

X-Api-Key: sk_test_xxxxxxxxxxxxxxxxxxxx

Endpoint

POST /api/v1/facade

Request

Send a JSON body with the fields defined in your organization's inbound mapping:

curl -X POST https://cloud.trua.com/api/v1/facade \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-15",
    "ssn": "123-45-6789"
  }'

The field names in your request (firstName, lastName, etc.) are specific to your organization. Trua Cloud translates them to its canonical model using the inbound customer mapping configured for your account.

Response

{
  "status": "success",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "verificationId": "VER-12345",
    "status": "processed",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}

The response fields are translated back through your outbound customer mapping, so they use your field naming conventions.

Every request returns a request_id that uniquely identifies this transaction. If you need to reference a specific request for support or debugging, provide this ID.

Field Mappings

Your Trua Cloud integrator configures customer mappings that translate between your field names and Trua's canonical model:

• Inbound mapping — translates your request fields to Trua's canonical fields
• Outbound mapping — translates Trua's response fields back to your naming conventions

For example, if your system uses firstName but Trua's canonical model uses given_name, the inbound mapping handles the translation automatically.

You do not need to change your field names. The mapping is configured on the Trua side and applied transparently to every request.

Mapping Types

Mappings are categorized by type (e.g., candidate, verification_result) and direction (inbound or outbound). Each mapping type has at most one active version per direction at any time.

Sandbox Testing

When using a test key (sk_test_), the Facade API returns sandbox fixture responses without processing the request through the mediation pipeline. This lets you validate your integration before any real data flows.

Sandbox Fixture Responses

Use the Test Harness in your site portal to try the facade endpoint interactively.

Testing with curl

# Success response (sandbox)
curl -X POST https://cloud.trua.com/api/v1/facade \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Test", "lastName": "User"}'

Error Handling

401 Unauthorized

Returned when the API key is missing, invalid, revoked, or disabled.

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

500 Internal Server Error

If the mediation pipeline encounters an error, the response includes a request_id for reference:

{
  "error": "processing_error",
  "message": "An error occurred processing your request.",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

When this happens, the request is recorded in the facade request queue with errored status. Your Trua Cloud integrator can investigate, hold, remediate, and retry the request through the admin interface.

Webhooks

Trua Cloud delivers webhook notifications for key verification lifecycle events. Configure your webhook endpoint with your Trua Cloud account representative.

Event Types

Facade-only customers receive the following webhook events:

Note: Events like invitation.sent and submission.completed apply only to collection customers who use the wizard. Facade-only customers receive verification-related events and data retention events.

Webhook Payload

Each webhook includes a standard envelope:

{
  "event": "<event_type>",
  "timestamp": "2026-02-03T14:30:00Z",
  "relying_party_code": "SOCURE",
  "data": { ... }
}

verification.completed

{
  "event": "verification.completed",
  "timestamp": "2026-02-03T14:30:00Z",
  "relying_party_code": "SOCURE",
  "data": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "verified_at": "2026-02-03T14:30:00Z",
    "score": 92,
    "status": "completed"
  }
}

verification.status_changed

{
  "event": "verification.status_changed",
  "timestamp": "2026-02-03T14:30:00Z",
  "relying_party_code": "SOCURE",
  "data": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "old_status": "pending",
    "new_status": "completed",
    "changed_at": "2026-02-03T14:30:00Z"
  }
}

data.retention_expiring

Sent at 60 days as a warning that data will be purged at 90 days.

{
  "event": "data.retention_expiring",
  "timestamp": "2026-02-03T14:30:00Z",
  "relying_party_code": "SOCURE",
  "data": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "submitted_at": "2025-12-05T10:00:00Z",
    "expires_at": "2026-03-05T10:00:00Z"
  }
}

data.terminated

Sent at 90 days when data is purged per the retention policy.

{
  "event": "data.terminated",
  "timestamp": "2026-02-03T14:30:00Z",
  "relying_party_code": "SOCURE",
  "data": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "terminated_at": "2026-03-05T00:00:00Z"
  }
}

Note: The data.terminated event does not include PII because it has already been purged. Use request_id to correlate with your records.

Webhook Headers

Signature Verification

Verify webhook authenticity using HMAC-SHA256:

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Reject requests where the timestamp is more than 5 minutes old to prevent replay attacks.

Delivery and Retries

• Webhooks are delivered via HTTP POST
• Your endpoint must return 2xx within 30 seconds (10-second connection timeout)
• Failed deliveries are retried up to 5 times with exponential backoff

Request Lifecycle

Every facade request goes through a defined lifecycle:

pending → processing → completed (success)
                     → errored (failure)
                        → held (under investigation)
                           → remediated (resolved)
                        → retry (reprocessed)

• pending — Request received and queued
• processing — Field mappings being applied, routing to handler
• completed — Successfully processed and response returned
• errored — Processing failed; visible in admin queue for remediation
• held — Integrator is investigating the error
• remediated — Investigation complete, notes recorded

Your Site Dashboard

As a facade-only customer, your site dashboard shows:

• API Keys — Your test and live keys
• Documentation — Integration guides assigned to your organization
• Test Harness — Interactive API testing (includes the facade endpoint)
• Facade API Usage — Total request count and active mapping count
• Integration Status — Readiness checks specific to facade customers

Facade-Specific Readiness Checks

Before go-live, your Trua Cloud admin verifies:

• Test and live API keys generated
• Portal user exists
• Documentation assigned
• Lifecycle stage configured
• Contract on file
• Customer mapping configured (at least one active inbound mapping)

Getting Help

• Documentation: Available in your site portal under Docs
• Account representative: Your primary contact for configuration, key rotation, and go-live
• Support: Email support@trua.com with your organization code and the request_id from any failed requests