Integration Guide

Socure One-Time Passcode API integration guide

This guide walks you through how to integrate with Socure’s /api/evaluation endpoint using the One-Time Passcode enrichment. You'll learn how to send phone number/email, deliver and validate One-Time Passcodes, and apply decision logic to support onboarding, authentication, fraud prevention, and compliance workflows.

Before you start

Make sure your RiskOS™ environment is provisioned with:

Postman Collection

The following Postman collection can be used to test the One-Time Passcode enrichment with the Evaluation endpoint.

📘

Testing Failure Paths in Sandbox:

Use these "Magic Values" to force specific error responses:

• Force Delivery Failure: Use phone number +11234567890.
• Force Invalid Code: Enter 000000 during the verification step. (Any other 6 digits will succeed).

Choose your environment

Start with Sandbox for development and testing, then move to Production for live applications.

https://riskos.sandbox.socure.com/api/evaluation

Get an API key

How it works

The One-Time Passcode integration follows an asynchronous pattern. Unlike a standard identity check, the API will pause and wait for the user to enter their code.

1. Initiate delivery: Send a POST /api/evaluation request with the user’s contact information (phone number and/or email).
2. Wait State: RiskOS™ creates a verification session and delivers the 6-digit code via SMS, Voice, or Email. The API returns an ON_HOLD status and a unique eval_id.
3. Verify and Resume: Once the user enters the code into your UI, submit a PATCH /api/evaluation/{eval_id} request to validate the code.
4. Final Decision: RiskOS™ resumes the workflow, applies final scoring logic, and returns a terminal decision (ACCEPT, REJECT, or REVIEW).

Integration flow

Your integration logic must handle the "In-Between" states, such as a user requesting a code resend or deciding to switch from an SMS delivery to an email delivery if they have poor cell reception.

sequenceDiagram
    participant User
    participant ClientApp
    participant RiskOS

    User->>ClientApp: Enter phone/email
    ClientApp->>RiskOS: POST /evaluation
    Note right of RiskOS: Pauses evaluation
    RiskOS-->>ClientApp: 200 OK (status: ON_HOLD, sub_status: Pending OTP Code)
    RiskOS->>User: Deliver OTP (SMS/Email/Voice)
    
    User->>ClientApp: Input 6-digit code
    ClientApp->>RiskOS: PATCH /evaluation/{eval_id} (otp.code: "123456")
    
    alt OTP Valid
        RiskOS-->>ClientApp: 200 OK (status: CLOSED, decision: ACCEPT)
    else OTP Invalid/Expired
        RiskOS-->>ClientApp: 400 Bad Request (msg: "Invalid code")
        
        opt User requests Resend
            ClientApp->>RiskOS: PATCH /evaluation/{eval_id} (otp.resend: true)
            RiskOS->>User: Re-deliver same code
        end
        
        opt User switches Channel (e.g., SMS to Email)
            ClientApp->>RiskOS: PATCH /evaluation/{eval_id} (actions.resume: true)
            ClientApp->>RiskOS: POST /evaluation (new email payload)
            RiskOS->>User: Deliver new code to Email
        end
    end

Quick response reference

Use this table to map RiskOS™ API responses to your application's routing and logic.

One-Time Passcode implementation timeline

1. Initiate delivery (POST)

   Submit the applicant's contact details to start the session. This triggers the initial One-Time Passocde delivery via SMS, Voice, or Email depending on your workflow configuration.

   
   

   • The "Wait" State: Because One-Time Passocde is an asynchronous process, RiskOS™ pauses the evaluation. You will receive a REVIEW decision and an ON_HOLD status.

   
   

   Key requirements:

   • SMS/Voice One-Time Passocde: Include phone_number in E.164 format (e.g., +14155550100).
   • Email One-Time Passocde: Include email address in valid RFC-5322 format (e.g., [email protected]).

   
   

   Example request

   cURL

   curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -d '{
     "id": "otp_session_123",
     "workflow": "your_otp_workflow",
     "data": {
       "individual": {
         "phone_number": "+14155550100",
         "email": "[email protected]"
       }
     }
   }'

2. Handle the "On-Hold" response

   Your application must capture the eval_id from the response. This ID is the unique "key" for the user's current session. By default, the OTP will remain active for 10 minutes. If the user does not authenticate with that OTP within that timeframe, you will need to execute a new OTP request in the workflow and get a new eval_id.

   
   

   • UI Action: When your frontend sees the "sub_status": "Pending OTP Code", transition to the 6-digit code entry screen.

   Example response

   JSON

   {
     "decision": "REVIEW",
     "eval_id": "123e4567-e89b-12d3-a456-426614174000",
     "status": "ON_HOLD",
     "sub_status": "Pending OTP Code"
   }

3. Manage "In-Between" UX logic

   While the evaluation is ON_HOLD, use the eval_id to handle non-linear user actions without breaking the session.

   
   

   Scenario: User didn't receive the code (Resend)

   If the user requests a resend, do not initiate a new evaluation. Use a PATCH request with the resend flag to deliver the same 6-digit code.

   
   

   • Same-Code Guarantee: Re-sends the existing code to ensure both the original and new messages are valid if they arrive out of order.
   • Persistence: Re-sending the code does not reset the 5-attempt verification limit.
   • TTL Constraint: This does not extend the 10-minute session expiration. If the original session has 2 minutes remaining, the resent code will also expire in 2 minutes.

   
   

   cURL

   curl -X PATCH https://riskos.sandbox.socure.com/api/evaluation/{eval_id} \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -d '{
     "id": "resend_request_001",
     "timestamp": "2026-02-13T16:38:37Z",
     "workflow": "your_otp_workflow",
     "data": {
       "individual": {
         "otp": { "resend": true }
       }
     }
   }'

4. Verify the code (PATCH)

   Once the user enters the code into your interface, submit it back to RiskOS™ to resume the evaluation. You must use the eval_id captured in Step 2: Handle the "On-Hold" response within the URL path.

   
   

   This request validates the code and automatically triggers the next steps in your workflow (e.g., final risk scoring or fraud checks).

   
   

   cURL

   curl -X PATCH https://riskos.sandbox.socure.com/api/evaluation/{eval_id} \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -d '{
     "id": "verify_step_001",
     "timestamp": "2026-02-13T16:38:37Z",
     "workflow": "your_otp_workflow",
     "data": {
       "individual": {
         "otp": { "code": "123456" }
       }
     }
   }'

5. Receive final decision

   If the code is correct, RiskOS™ automatically resumes the workflow to perform final scoring. The session typically moves from ON_HOLD to a terminal CLOSED status.

   
   

   A successful One-Time Passcode verification typically results in an ACCEPT decision, though this depends on your specific workflow rules and other risk signals.

   
   

   • Success is not always the end: If the response returns status: "ON_HOLD" with sub_status: "More information needed", device possession is verified, but you must now PATCH the evaluation with the user's manual PII (Name, Address, SSN, etc.) to complete the identity profile.

   • Implementation note: If the evaluation results in a REJECT or REVIEW decision even after successful OTP verification, check your workflow's auxiliary risk modules (like Phone Risk or Digital Intelligence) for high-risk signals.

   
   

   Example response

   Example final response (Success)Example response (More information needed)

   {
     "id": "verify_attempt_001",
     "eval_id": "123e4567-e89b-12d3-a456-426614174000",
     "status": "CLOSED",
     "sub_status": "Approve",
     "decision": "ACCEPT",
     "tags": [
       "OTP_VERIFIED",
       "Low Risk"
     ]
   }

   {
     "id": "verify_attempt_001",
     "eval_id": "123e4567-e89b-12d3-a456-426614174000",
     "status": "ON_HOLD",
     "sub_status": "More information needed",
     "decision": "REVIEW",
     "tags": [
       "OTP Approved",
       "Prefill Unsuccessful"
     ]
   }

State and routing reference

Use the following table to map RiskOS™ response fields to your frontend routing logic. This ensures your UI always reflects the current state of the user's verification session.

Handling the eval_id

Your frontend state management (Redux, Context API, etc.) must persist the eval_id as long as the session is ON_HOLD.

📘

Persistence note:

If the user refreshes their browser, you must retrieve the eval_id from your local storage or backend to ensure they can resume the same session without triggering a new (and potentially rate-limited) One-Time Passcode request.

Technical appendix: API reference

This section provides the exhaustive schema definitions for the /api/evaluation endpoint when used with the One-Time Passcode enrichment.

1. Initiation delivery schema (POST)

Use these fields to start a new verification session.

POST https://riskos.sandbox.socure.com/api/evaluation

POST https://riskos.socure.com/api/evaluation

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

{
  "id": "otp-001",
  "timestamp": "2025-09-30T10:00:00Z",
  "workflow": "individual_onboarding",
  "data": {
    "individual": {
      "phone_number": "+14155550100",
      "email": "[email protected]"
    }
  }
}

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "id": "otp-001",
  "timestamp": "2025-09-30T10:00:00Z",
  "workflow": "individual_onboarding",
  "data": {
    "individual": {
      "phone_number": "+14155550100",
      "email": "[email protected]"
    }
  }
}'

{
  "decision": "REVIEW",
  "eval_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "ON_HOLD",
  "sub_status": "Pending OTP Code",
  "data_enrichments": [
    {
      "enrichment_name": "Deliver OTP SMS",
      "enrichment_provider": "SocureOTP",
      "status_code": 200,
      "response": {
        "verificationId": "aaa4703c-16b6-4a25-9c70-58722a26c7ed"
      }
    }
  ]
}

2. Management and verification schema (PATCH)

Use these fields to handle user actions while the evaluation is ON_HOLD. All management actions require the eval_id captured from the initial delivery response.

Handling channel switches: To switch from SMS to Email delivery, you must first "clear" the paused state.

1. Send a PATCH with "actions": { "resume": true }.
2. Once the session is resumed, send a new POST /api/evaluation with the new contact method.

PATCH https://riskos.sandbox.socure.com/api/evaluation/{eval_id}

PATCH https://riskos.socure.com/api/evaluation/{eval_id}

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-API-Version: 2025-01-01.orion   # optional – pins a specific API version

{
"id": "otp-resend-001",
"timestamp": "2025-09-30T10:07:00Z",
"workflow": "individual_onboarding",
"data": {
  "individual": {
    "otp": {
      "resend": true
    }
  }
}
}

curl -X PATCH https://riskos.sandbox.socure.com/api/evaluation/{eval_id} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "id": "otp-resend-001",
  "timestamp": "2025-09-30T10:07:00Z",
  "workflow": "individual_onboarding",
  "data": {
    "individual": {
      "otp": {
        "resend": true
      }
    }
  }
}'

3. Response and status reference

The following fields are used to manage frontend routing and determine the session state.

{
  "decision": "ACCEPT",
  "status": "CLOSED",
  "sub_status": "Approve",
  "tags": ["OTP_VERIFIED"],
  "data_enrichments": [
    {
      "enrichment_name": "Verify OTP SMS",
      "enrichment_provider": "SocureOTP",
      "status_code": 200,
      "response": {
        "attemptCount": 1,
        "status": "approved",
        "verificationId": "aaa4703c-16b6-4a25-9c70-58722a26c7ed"
      }
    }
  ]
}

Security and implementation guidelines

📘

Message Customization:

One-Time Passcode message templates—including custom branding, specific wording, and multi-language support—are configured at the account level. These cannot be modified dynamically via the /api/evaluation payload. To update your SMS, Voice, or Email templates, please contact your Socure Account Manager or Support Team.

Validation checklist

Testing requirements

Schema & API compliance

Security & monitoring