Integration Notes

⚠️
Cerebrum may add new Status or Score values over time without advance notice and without treating that as a breaking API change. Integrations must be coded defensively so unknown values do not break parsing, syncing, or downstream workflows.

Cerebrum may add more Status or Score values over time without changing our API contract or notifying integrators in advance. Treat these fields as extensible enums.

Your integration should handle unknown Status and Score values safely:

Key workflow completion off known terminal statuses, especially Status: COMPLETE.
Key outcome/disposition off known final score values after the order is complete.

ℹ️
Status is extensible. Cerebrum may add new status values without advance notice. If your integration receives an unknown status, store the raw value and treat it as non-terminal by default. Do not trigger downstream completion workflows unless the status is a known terminal value such as COMPLETE.

Order Status

What it is: The workflow lifecycle indicator. It tells you where the order is in the processing pipeline, nothing more.

Who controls it: Set automatically by the system or manually by a processor clicking "Report Results."

Possible values for order status can be found here.

Key point: COMPLETE only means the order has been reviewed by someone (or passed automatically). It does not imply the identity was verified or that there are no alerts. Completion and outcome are separate, an order can be complete and still have alerts.

Use Status for:

Determining whether an order is done and ready to sync
Triggering downstream actions in your integration

ℹ️
Status is extensible. Cerebrum may add new status values without advance notice. If your integration receives an unknown status, store the raw value and treat it as non-terminal by default. Do not trigger downstream completion workflows unless the status is a known terminal value such as COMPLETE.

Order Score

What it is: The business disposition label. It describes what the outcome means - the human-readable verdict on the verification.

Who controls it: Set automatically on clean passes, or manually by a processor after review.

Possible values for order score can be found here.

Key points:

ON_HOLD is an intermediate label. It does not mean a final result is coming next automatically - it just means the CRA is still internally reviewing. Wait for the score to update before acting.
A processor can set Score: ID_VERIFIED even when Alert: ALERTS_FOUND - this is intentional. It means the processor reviewed the alerts and determined the ID is still approvable.

Use Score for:

Understanding the outcome/disposition of the verification

ℹ️
Score is extensible. Cerebrum may add new score values without advance notice. If your integration receives an unknown score, our recommendation is either to ignore it, or to store the raw value and map it to a default "unknown", "pending review", or equivalent internal disposition. Do not infer outcomes from an unknown score.

Order Alert

What it is: A simple binary signal that indicates whether any alerts were found on the order. It is the most simplified view of the outcome.

Who controls it: Set automatically by the system when the order reaches COMPLETE.

Possible values for order alert can be found here.

Key points:

Alert is always NULL until the order status becomes COMPLETE.
ALERTS_FOUND as the Alert value is independent of the Score. A processor can review the alerts and still set the Score to ID_VERIFIED if they determine the order is approvable.
Do not use Alert as your primary decision-making field. An order can be COMPLETE with ALERTS_FOUND and Score: ID_VERIFIED simultaneously - meaning it passed.

Use Alert for:

A quick binary flag for auditing or logging purposes
Do not use it as the primary field to determine pass/fail

Order Workflow

flowchart TD
    A([User Completes Verification]) --> B{Passes Automatically?}

    B -- Yes --> C[Status: COMPLETE 
                    Score: ID_VERIFIED
                    Alert: NO_ALERTS_FOUND
                ]

    B -- No --> D[Status: PENDING
    Score: PENDING
    Alert: NULL]

    D --> E[Processor Reviews Order]

    E --> F{Processor Decision}

    F -- Alerts Found on ID --> G[Score: PENDING
    Alert: ALERTS_FOUND]

    G --> H{Processor Sets Final Score}

    H -- Approves --> I[Status: COMPLETE
    Score: ID_VERIFIED
    Alert: ALERTS_FOUND]

    H -- Rejects --> J[Status: COMPLETE
    Score: ID_NOT_VERIFIED
    Alert: ALERTS_FOUND]

    F -- No Issues --> K[Status: COMPLETE
    Score: ID_VERIFIED
    Alert: NO_ALERTS_FOUND]

    F -- Needs More Time --> L[Score: ON_HOLD
    Status: PENDING]

    L -- Review Complete --> F

    style C fill:#d4edda,stroke:#28a745,color:#000
    style I fill:#fff3cd,stroke:#ffc107,color:#000
    style J fill:#f8d7da,stroke:#dc3545,color:#000
    style K fill:#d4edda,stroke:#28a745,color:#000
    style L fill:#e2e3e5,stroke:#6c757d,color:#000
    style D fill:#cce5ff,stroke:#004085,color:#000

How They Work Together

These three fields are set independently and can appear in combinations that seem contradictory at first glance. Here are the most common scenarios:

Scenario 1: Automatic Pass (Clean Verification)

The user completes ID verification and passes automatically with no issues.

Status: COMPLETE
Score:  ID_VERIFIED
Alert:  NO_ALERTS_FOUND

Scenario 2: Needs Manual Review

The system flagged something and a processor needs to review the order before a final score is set.

Status: PENDING
Score:  REVIEW_REQUIRED
Alert:  NULL

ℹ️
A processor should review this order and click "Report Results."

Scenario 3: Processor Approved Despite Alerts

A processor reviewed the alerts (e.g., IP address flag) and determined the ID is still valid.

Status: COMPLETE
Score:  ID_VERIFIED
Alert:  ALERTS_FOUND

ℹ️
This is expected and valid. The alert exists, but the processor cleared it. Key off Score, not Alert.

Scenario 4: CRA Internally Reviewing (On Hold)

The CRA is still checking the document. This is an intermediate state - do not act on it yet.

Status: PENDING
Score:  ON_HOLD
Alert:  NULL

ℹ️
Wait for the score to update to a final value before taking action.

Scenario 5: Verification Failed

The processor reviewed the order and determined the identity could not be verified.

Status: COMPLETE
Score:  ID_NOT_VERIFIED
Alert:  ALERTS_FOUND

Integration Recommendations

Follow these rules when building your integration:

1. Use Status as the source of truth for completion

Only act on an order (e.g., trigger downstream syncs) when Status = COMPLETE. Do not use Score or Alert to determine whether an order is done.

2. Use Score as the disposition label

When Status = COMPLETE, read the Score and sync it back to your system 1:1.

3. Do not use Alert as a pass/fail signal

Alert is a binary summary, but it does not account for processor overrides. An ALERTS_FOUND alert alongside Score: ID_VERIFIED means the order was approved. Always defer to Score for the actual outcome.

4. Watch for ON_HOLD - it is not final

If you receive a webhook with Status: IN_PROGRESS and/or Score: ON_HOLD, do not treat this as a terminal state. The CRA is still reviewing. Wait for a subsequent score update.

Quick Summary

Field	Purpose	Source of Truth For	Key Caution
Status	Workflow lifecycle	Is the order done?	`COMPLETE` ≠ passed
Score	Business disposition	What was the outcome?	`ON_HOLD` is not final
Alert	Binary alert flag	Audit / logging	Do not use for pass/fail logic