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, which typically remains valid for 10 minutes.

   
   

   • 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