TalvifyCommand
Menu
Sign inStart Command

Command developer guide · REST ingestion v1

Provide operational facts.
Keep control of your data.

Your integration sends a narrow, versioned contract of approved facts. Command validates, evaluates, and consolidates them into governed signals without replicating your source system.

Private betaContract 2026-08-01Schema 1.0500 records / batch

Customer onboarding

Six controlled steps from source to signal.

Business owners define the use case and controls. Customer IT owns extraction and mapping. A Command administrator owns source credentials and production release.

01

Agree the use case

Choose the outcome and control groups before sending data. This determines the minimum fields Command is allowed to receive.

02

Create a source

A workspace administrator creates a REST source. Command returns the bearer credential once; store it in your secrets manager.

03

Map safe fields

Transform ERP, CRM, WMS, billing, or service records into the normalized contract. Exclude bodies, attachments, credentials, and full profiles.

04

Send a batch

POST up to 500 facts with a unique idempotency key. Command validates the entire batch before anything is persisted.

05

Review results

Accepted facts are evaluated by active controls and consolidated. Rejected batches return a precise error without partial ingestion.

06

Operate securely

Monitor batch status, retry safely, rotate or revoke credentials, and keep customer-side logs that contain no bearer tokens.

Minimal request contract

Send normalized facts—not unrestricted payloads.

Unknown fields reject the complete batch. Full records, message bodies, attachments, clinical content, passwords, banking credentials, and connector secrets are outside the ingestion contract.

Before production

Validate the field map in the DEV Lab, confirm active control coverage, prove consolidation and ownership, rotate the test credential, and obtain the workspace owner’s release approval.

POST /api/v1/ingestion/batches
Authorization: Bearer tvy_ing_…
Idempotency-Key: erp-20260818-001
Content-Type: application/json

{
  "contract_version": "2026-08-01",
  "schema_version": "1.0",
  "workspace_id": "ws_issued_by_talvify",
  "source_system": "oracle_ebs",
  "records": [{
    "record_id": "INV-10482",
    "category": "revenue",
    "event_type": "invoice_overdue",
    "occurred_at": "2026-08-18T14:30:00Z",
    "expected_value": "2026-08-16",
    "observed_value": "open",
    "organization_ref": "OU-12",
    "counterparty_ref": "CUST-884",
    "owner_ref": "TEAM-AR",
    "status_ref": "OVERDUE",
    "evidence_ref": "oracle:invoice:10482"
  }]
}

Safe delivery

Retries never need to create duplicate work.

Use one idempotency key for one immutable batch. An identical retry returns the original result; changed content under the same key fails with a conflict.

StatusMeaningCustomer action
400Invalid contract or unknown field

Correct the mapping; do not retry unchanged content.

401Missing, invalid, or revoked credential

Stop the sender and ask a workspace administrator to rotate or replace the credential.

409Idempotency key reused with different content

Generate a new key only for genuinely new content. Never mutate a previously keyed batch.

429Rate limit reached

Retry with exponential backoff and jitter; preserve the same idempotency key.

5xxTemporary service failure

Retry the identical request with backoff. Escalate with the request ID if failures continue.

Governed resolution evidence

Close automatically only when policy and evidence agree.

Send an explicit resolution event with a fresh provider evidence reference and the exact signal source reference returned by Command. Manual-only policy leaves the signal open, confirmation policy marks resolution detected, and evidence auto-close records a system resolution. A later recurrence reopens the same governed signal.

"record_id": "PAY-10482-RESOLVED",
"category": "revenue",
"event_type": "payment_received",
"occurred_at": "2026-08-24T14:30:00Z",
"status_ref": "paid",
"evidence_ref": "odoo:payment:7781",
"attributes": {
  "signal_source_ref": "ingestion:revenue|invoice_overdue|odoo|OU-12|CUST-884|TEAM-AR"
}

Who resolves the issue?

The integration supplies evidence. People correct the source system.

Command does not edit the ERP, CRM, WMS, or mailbox record. It explains the governed exception, assigns an accountable owner, and records the outcome. The owner fixes the operational problem in its authoritative system and closes the loop in Command.

See the complete lifecycle
CREDENTIAL LIFECYCLE
Create
Admin only
Reveal
Once
Store
Customer vault
Rotate
Controlled
Revoke
Immediate

Need an integration review?

Validate the contract before production.

Contact Talvify