Integrate One-Time Passcode (OTP)

Endpoint

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

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

Authentication and headers

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

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

Example request

{
  "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]"
    }
  }
}'

Request schema

Top-level fields

  <th>
    Type
  </th>

  <th>
    Required
  </th>

  <th>
    Description
  </th>

  <th>
    Example
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    Required
  </td>

  <td>
    Required, customer-defined unique identifier for the request.

    This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows.
  </td>

  <td>
    `"a86580cc-1733-4188-86b5-717166e1db8c"`
  </td>
</tr>

<tr>
  <td>
    `timestamp`
  </td>

  <td>
    String `<Date-Time>`
  </td>

  <td>
    Required
  </td>

  <td>
    RFC 3339 timestamp indicating when the evaluation request was initiated by your system.
  </td>

  <td>
    `"2025-05-02T12:44:22.059Z"`
  </td>
</tr>

<tr>
  <td>
    `workflow`
  </td>

  <td>
    String
  </td>

  <td>
    Required
  </td>

  <td>
    Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > **Developer Workbench** > **Integration Checklist**. <br /><br /> **Note:** The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request.
  </td>

  <td>
    `"consumer_onboarding"`
  </td>
</tr>

<tr>
  <td>
    `data`
  </td>

  <td>
    Object
  </td>

  <td>
    Required
  </td>

  <td>
    Main payload containing consumer information, device data, and event details for evaluation.
  </td>

  <td></td>
</tr>

<tr>
  <td>
    →`individual`
  </td>

  <td>
    Object
  </td>

  <td>
    Required
  </td>

  <td>
    Primary identity object containing individual's information.
  </td>

  <td>
    See `individual` schema below.
  </td>
</tr>

individual fields

Example response

{
  "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"
      }
    }
  ]
}

Response schema

data_enrichments fields - OTP Delivery (Initial POST)

This object appears in the response of the initial POST /api/evaluation call. Use these fields to confirm the code was successfully handed off to the delivery provider.

Endpoint

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

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

Authentication and headers

Include your API key in the Authorization header as a Bearer token, along with standard JSON headers:

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

Example request

{
"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
      }
    }
  }
}'

Request schema

Top-level fields

  <th>
    Type
  </th>

  <th>
    Required
  </th>

  <th>
    Description
  </th>

  <th>
    Example
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    Required
  </td>

  <td>
    Required, customer-defined unique identifier for the request.

    This value must be unique for each evaluation. Reusing an ID causes RiskOS™ to treat the request as a re-run and can impact processing behavior, results, and downstream workflows.
  </td>

  <td>
    `"a86580cc-1733-4188-86b5-717166e1db8c"`
  </td>
</tr>

<tr>
  <td>
    `timestamp`
  </td>

  <td>
    String `<Date-Time>`
  </td>

  <td>
    Required
  </td>

  <td>
    RFC 3339 timestamp indicating when the evaluation request was initiated by your system.
  </td>

  <td>
    `"2025-05-02T12:44:22.059Z"`
  </td>
</tr>

<tr>
  <td>
    `workflow`
  </td>

  <td>
    String
  </td>

  <td>
    Required
  </td>

  <td>
    Your environment-specific workflow identifier. You can find this value in the RiskOS™ Dashboard > **Developer Workbench** > **Integration Checklist**. <br /><br /> **Note:** The workflow name must be unique within your RiskOS™ environment. It is not scoped by use case and must identify a single active workflow for each Evaluation API request.
  </td>

  <td>
    `"consumer_onboarding"`
  </td>
</tr>

<tr>
  <td>
    `actions`
  </td>

  <td>
    Object
  </td>

  <td>
    Optional
  </td>

  <td>
    A top-level container for instructions that modify the lifecycle of the current evaluation session.
  </td>

  <td>
    `{"actions": {...}}`
  </td>
</tr>

<tr>
  <td>
    → `resume`
  </td>

  <td>
    Boolean
  </td>

  <td>
    Required
  </td>

  <td>
    Set to `true` to force the workflow out of an `ON_HOLD` state. This bypasses the current pending step (e.g., OTP entry) to allow the user to fix a typo or switch delivery channels.
  </td>

  <td>
    `true`
  </td>
</tr>

<tr>
  <td>
    `data`
  </td>

  <td>
    Object
  </td>

  <td>
    Required
  </td>

  <td>
    Main payload containing consumer information, device data, and event details for evaluation.
  </td>

  <td></td>
</tr>

<tr>
  <td>
    →`individual`
  </td>

  <td>
    Object
  </td>

  <td>
    Required
  </td>

  <td>
    Primary identity object containing individual's information.
  </td>

  <td>
    See `individual` schema below.
  </td>
</tr>

individual.otp fields

Example response

{
  "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"
      }
    }
  ]
}

📘

Note: The API response does not include the data object you submitted in the request (for example, data.individual.address). The response contains only evaluation metadata, decision fields, and data_enrichments. The RiskOS™ Dashboard may display a combined view that includes input data alongside the response.

To retrieve the original input data, use GET /api/evaluation/{eval_id}?include_input=true.

Response schema

Top-level Fields

data_enrichments fields - OTP Verification

Data Validation Requirements:

• Validate phone numbers in E.164 format before sending requests.
• Validate email addresses using proper regex patterns.
• Sanitize all user inputs to prevent injection attacks.
• Never log or store OTP codes in plain text or your database.

Security Implementation:

• Always use HTTPS for all API requests.
• Implement proper request/response logging with correlation IDs.
• Redact sensitive data (OTP codes, phone numbers) from logs.
• Use secure storage for API keys and credentials.

Robust Error Handling:

• Implement retry logic for network timeouts and 5xx errors.
• Handle Rate Limits (HTTP 429): Implement exponential backoff based on these system thresholds:
  • OTP Generation: 5 requests per minute per destination.
  • OTP Verification: 10 requests per minute per verificationId.
• Provide clear, actionable error messages to users based on the sub_status returned.
• Log errors with sufficient detail (including eval_id and verificationId) for debugging.

Optimal User Experience:

• Display remaining attempts clearly to users. Note that requesting a Resend does not reset the 5-attempt limit.
• Show a countdown timer during the 10-minute cooling period if a lockout occurs.
• Provide resend functionality but notify the user that the original 10-minute session expiration still applies.
• Allow channel switching (e.g., SMS to Email) by using the actions.resume: true sequence to clear the session before restarting.
• Give immediate feedback on code entry to prevent users from accidentally double-submitting and wasting attempts.