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:

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

Use for live applications with real customer data.

📘
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 --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": "[email protected]",
      "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 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: '[email protected]',
        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();

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": "[email protected]",
            "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 --request GET \
  --url "https://riskos.sandbox.socure.com/api/evaluation/eval_abc123" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

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}`);

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 --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 --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. See Rate Limits for more information.