## 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:

1. Get your API key from the [**Developer Workbench > API Keys**](https://help.socure.com/riskos/docs/integration-guide-authentication#/) section in the RiskOS™ Dashboard.
2. Include in requests using the `Authorization` header.
3. 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
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

```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

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

#### JavaScript

```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

```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
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
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:

```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.