API Requests

Quick Reference

Sandbox Base URL

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

Production Base URL

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

Authentication

Authorization: Bearer YOUR_API_KEY

Content Type

Content-Type: application/json

Environment Setup

Base URLs

Choose the appropriate environment for your integration:

HTTP

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

Use for live applications with real customer data.

HTTP

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

Use for development, testing, and integration verification.

📘 Important for Sandbox Testing
The Sandbox environment requires specific field values to return properly formatted responses. Modifying input data outside of documented test values may result in HTTP errors.

Authentication

All API requests require authentication using Bearer tokens:

Get your API key from the Developer Workbench > API Keys section in the RiskOS™ Dashboard.
Include in requests using the Authorization header.
Keep it secure- never expose API keys in client-side code.

Authorization: Bearer YOUR_API_KEY

HTTP Methods and Usage

The RiskOS™ API follows REST conventions with standard HTTP methods:

Method	Purpose	Common Use Cases
`POST`	Create resources	Start new evaluation
`GET`	Retrieve data	Fetch evaluation results
`PUT`	Replace resources	Update evaluation state
`PATCH`	Partial updates	Add additional data points

Required 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      # For POST/PUT/PATCH requests

Optional Headers

Header	Purpose	Example
`X-API-Version`	Pins a specific API version to ensure backward compatibility with evolving RiskOS™ endpoints.	`2025-01-01.orion`
`Accept`	Indicates the preferred response format. Optional since all responses are JSON by default.	`application/json`

Complete Request Examples

Start an Evaluation

Create a new evaluation with customer data:

cURL

curl --request POST \
--url "https://riskos.sandbox.socure.com/api/evaluation" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "id": "customer-onb-12345",
  "timestamp": "2024-12-01T08:15:30.456Z",
  "workflow": "consumer_onboarding",
  "data": {
    "individual": {
      "given_name": "Jane",
      "family_name": "Doe",
      "email": "jane.doe@example.com",
      "phone_number": "+1-555-123-4567",
      "address": {
        "line_1": "123 Main St",
        "locality": "San Francisco",
        "major_admin_division": "CA",
        "postal_code": "94105",
        "country": "US"
      }
    }
  }
}'

JavaScript

const response = await fetch('https://riskos.sandbox.socure.com/api/evaluation', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.YOUR_API_KEY}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    id: 'customer-onb-12345',
    timestamp: new Date().toISOString(),
    workflow: 'consumer_onboarding',
    data: {
      individual: {
        given_name: 'Jane',
        family_name: 'Doe',
        email: 'jane.doe@example.com',
        phone_number: '+1-555-123-4567',
        address: {
          line_1: '123 Main St',
          locality: 'San Francisco',
          major_admin_division: 'CA',
          postal_code: '94105',
          country: 'US'
        }
      }
    }
  })
});

const evaluation = await response.json();

Python

import requests
import os
from datetime import datetime

url = "https://riskos.sandbox.socure.com/api/evaluation"
headers = {
    "Authorization": f"Bearer {os.getenv('YOUR_API_KEY')}",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "id": "customer-onb-12345",
    "timestamp": datetime.utcnow().isoformat() + "Z",
    "workflow": "consumer_onboarding",
    "data": {
        "individual": {
            "given_name": "Jane",
            "family_name": "Doe",
            "email": "jane.doe@example.com",
            "phone_number": "+1-555-123-4567",
            "address": {
                "line_1": "123 Main St",
                "locality": "San Francisco",
                "major_admin_division": "CA",
                "postal_code": "94105",
                "country": "US"
            }
        }
    }
}

response = requests.post(url, headers=headers, json=payload)
evaluation = response.json()

Retrieve the Evaluation Results

Get the current state and results of an evaluation:

cURL

curl --request GET \
--url "https://riskos.sandbox.socure.com/api/evaluation/eval_abc123" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Accept: application/json"

JavaScript

const response = await fetch('https://riskos.sandbox.socure.com/api/evaluation/eval_abc123', {
  headers: {
    'Authorization': `Bearer ${process.env.YOUR_API_KEY}`,
    'Accept': 'application/json'
  }
});

const evaluation = await response.json();
console.log(`Risk Score: ${evaluation.risk_score}`);

Python

import requests
import os

response = requests.get(
    "https://riskos.sandbox.socure.com/api/evaluation/eval_abc123",
    headers={
        "Authorization": f"Bearer {os.getenv('YOUR_API_KEY')}",
        "Accept": "application/json"
    }
)

evaluation = response.json()
print(f"Risk Score: {evaluation['risk_score']}")

Update Evaluation State

Change the status of an evaluation after manual review:

cURL

curl --request PUT \
  --url https://riskos.socure.com/api/evaluation/eval_id/state \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "accept: application/json" \
  --header "content-type: application/json" \
  --data '{
    "workflow": "consumer_onboarding",
    "decision": "REVIEW",
    "status": "OPEN",
    "sub_status": "In Review",
    "notes": "Verification documents pending re-check",
    "attachments": [
      {
        "file_name": "case.jpeg",
        "file_data": "JVBERi0xLjUKJeLjz9MKMyAwIG9iago8PC9..."
      }
    ]
  }'

Add Additional Data

Partially update an evaluation with new information:

cURL

curl --request PATCH \
  --url https://riskos.socure.com/api/evaluation/{eval_id} \
  --header "accept: application/json" \
  --header "content-type: application/json" \
  --data '{
    "id": "onb-12345",
    "timestamp": "2023-12-01T08:15:30.456Z",
    "workflow": "consumer_onboarding",
    "data": {
      "device": {
        "id": "DEVICE-123456",
        "ip_address": "192.168.1.10",
        "session": "UPDATED-SESSION-1234"
      }
    }
  }'

Parameter Types

Path Parameters

Required in URLs to specify the resource:

/api/evaluation/{eval_id}          # eval_id is a path parameter
/api/evaluation/{eval_id}/state    # eval_id is required

Body Parameters

Sent in the request body as JSON:

{
  "id": "string",           // Required: Your unique identifier
  "workflow": "string",     // Required: Workflow type
  "data": { ... },          // Required: Customer data
  "timestamp": "string"     // Optional: ISO 8601 timestamp
}

Best Practices

Security

Never hardcode API keys in source code
Use environment variables for sensitive configuration
Implement proper key rotation procedures
Use HTTPS only for all API requests
Validate SSL certificates in production

Performance

Implement request timeouts (recommended: 30 seconds)
Use connection pooling for high-volume applications
Cache evaluation results when appropriate
Implement exponential backoff for retries
Monitor rate limits and adjust request frequency

Reliability

Always check response status codes
Implement proper error handling
Log request/response data for debugging
Use unique request IDs for tracing
Implement circuit breaker patterns for high availability

Development

Start with Sandbox environment for all testing
Use realistic test data to verify integration
Implement comprehensive logging
Test error scenarios thoroughly
Document your integration for team members

Rate Limits

The RiskOS™ API implements rate limiting to ensure service stability:

Sandbox: 100 requests per minute
Production: Contact support for limits based on your plan

When rate limited, you'll receive a 429 status code with retry information in headers.