StrataWeave Developer Hub

Introduction

The StrataWeave API provides programmatic access to our enrollment data normalization platform. Use our API to submit enrollment files, monitor processing status, retrieve normalized data, and manage vendor configurations.

Key Features

• RESTful API design with JSON payloads
• OAuth 2.0 authentication
• Webhook notifications for async processing
• Comprehensive error reporting
• Rate limiting: 1000 requests per hour
• Full audit trail for compliance

Authentication

StrataWeave uses OAuth 2.0 with client credentials flow for API authentication. You'll need an API key and secret which can be obtained from your account dashboard.

Obtaining an Access Token

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Access Token

Include the access token in the Authorization header for all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Core Endpoints

File Submission

POST /files/upload

Submit an enrollment file for processing. StrataWeave will automatically detect the file format and vendor.

Request

POST /files/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [binary file data]
vendor_hint: "partner_name" (optional)
callback_url: "https://yourapp.com/webhooks/strataweave" (optional)

Response

{
  "job_id": "job_a1b2c3d4e5f6",
  "status": "processing",
  "file_name": "enrollment_data_2025.csv",
  "detected_vendor": "ABC Insurance Co",
  "detected_format": "CSV",
  "row_count": 2047,
  "submitted_at": "2025-01-09T14:32:00Z",
  "estimated_completion": "2025-01-09T14:39:00Z"
}

Status Values

Status	Description
queued	File received and queued for processing
processing	File is currently being normalized
completed	Processing completed successfully
completed_with_errors	Processing completed but some records failed validation
failed	Processing failed (see error details)

Check Job Status

GET /jobs/{job_id}

Retrieve the current status and details of a processing job.

Response

{
  "job_id": "job_a1b2c3d4e5f6",
  "status": "completed",
  "file_name": "enrollment_data_2025.csv",
  "vendor": "ABC Insurance Co",
  "format": "CSV",
  "submitted_at": "2025-01-09T14:32:00Z",
  "completed_at": "2025-01-09T14:37:23Z",
  "processing_time_seconds": 323,
  "statistics": {
    "total_rows": 2047,
    "valid_rows": 2041,
    "invalid_rows": 6,
    "warnings": 12
  },
  "download_urls": {
    "normalized_data": "https://api.strataweave.com/v1/files/job_a1b2c3d4e5f6/output",
    "error_report": "https://api.strataweave.com/v1/files/job_a1b2c3d4e5f6/errors",
    "original_file": "https://api.strataweave.com/v1/files/job_a1b2c3d4e5f6/original"
  }
}

Download Normalized Data

GET /files/{job_id}/output

Download the normalized enrollment data in your preferred format.

Query Parameters

Parameter	Type	Description
format	string	Output format: json, csv, xml (default: json)
include_metadata	boolean	Include processing metadata (default: false)

Response (JSON format)

{
  "job_id": "job_a1b2c3d4e5f6",
  "vendor": "ABC Insurance Co",
  "processed_at": "2025-01-09T14:37:23Z",
  "records": [
    {
      "member_id": "M123456",
      "first_name": "John",
      "last_name": "Smith",
      "date_of_birth": "1985-03-15",
      "ssn": "***-**-1234",
      "email": "[email protected]",
      "phone": "+1-555-123-4567",
      "address": {
        "street": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip": "62701"
      },
      "coverage": {
        "plan_id": "PLAN001",
        "effective_date": "2025-01-01",
        "termination_date": null,
        "coverage_type": "employee_plus_spouse"
      },
      "dependents": []
    }
  ]
}

Error Report

GET /files/{job_id}/errors

Retrieve detailed error information for records that failed validation.

Response

{
  "job_id": "job_a1b2c3d4e5f6",
  "total_errors": 6,
  "errors": [
    {
      "row_number": 42,
      "severity": "error",
      "field": "date_of_birth",
      "message": "Invalid date format. Expected YYYY-MM-DD, got '03/15/85'",
      "original_value": "03/15/85",
      "suggested_fix": "2085-03-15 or 1985-03-15"
    },
    {
      "row_number": 127,
      "severity": "error",
      "field": "ssn",
      "message": "SSN failed validation: invalid format",
      "original_value": "123-45-678",
      "suggested_fix": "Ensure SSN is 9 digits in format XXX-XX-XXXX"
    }
  ]
}

Vendor Management

List Vendors

GET /vendors

Retrieve all configured vendor mappings for your account.

Response

{
  "vendors": [
    {
      "vendor_id": "vnd_abc123",
      "name": "ABC Insurance Co",
      "status": "active",
      "file_formats": ["csv", "excel", "fixed_width"],
      "last_file_received": "2025-01-09T10:15:00Z",
      "total_files_processed": 247,
      "average_processing_time_seconds": 315
    }
  ]
}

Get Vendor Details

GET /vendors/{vendor_id}

Retrieve detailed configuration for a specific vendor.

Update Vendor Configuration

PUT /vendors/{vendor_id}

Update vendor mapping rules and validation settings.

Webhooks & Notifications

StrataWeave provides two methods to receive notifications when file processing completes: Webhooks (push notifications) and Polling (pull-based).

Method 1: Webhooks (Recommended)

Configure webhook URLs to receive real-time notifications when files complete processing. Webhooks are sent immediately upon job completion, eliminating the need for polling.

Configuring Webhooks

Set your webhook URL in your partner configuration:

POST /partner-config/{partner_id}
Content-Type: application/json

{
  "webhook_url": "https://yourapp.com/webhooks/strataweave",
  "webhook_secret": "your_webhook_secret_for_verification",
  "webhook_events": ["job.completed", "job.failed"]
}

Webhook Payload

POST https://yourapp.com/webhooks/strataweave
Content-Type: application/json
X-StrataWeave-Signature: sha256=abc123...

{
  "event": "job.completed",
  "job_id": "run_a1b2c3d4",
  "status": "completed",
  "timestamp": "2025-01-09T14:37:23Z",
  "partner_id": "usaa",
  "original_filename": "enrollment_20250109.csv",
  "statistics": {
    "total_rows": 2047,
    "valid_rows": 2041,
    "invalid_rows": 6
  },
  "download_urls": {
    "normalized_data": "https://api.strataweave.com/download/run_a1b2c3d4",
    "error_report": "https://api.strataweave.com/errors/run_a1b2c3d4"
  }
}

Webhook Events

Event	Description
job.queued	File received and queued for processing
job.processing	Processing has started
job.completed	Processing completed successfully
job.failed	Processing failed

Verifying Webhook Signatures

All webhooks include an X-StrataWeave-Signature header for security verification.

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Method 2: Polling (Alternative)

If webhooks aren't suitable for your infrastructure, you can poll the status endpoint to check for completed files.

Poll for Status

GET /status

Returns all recent file processing runs with their current status.

Response

{
  "updated_at": "2025-01-09T14:37:23Z",
  "runs": [
    {
      "run_id": "run_a1b2c3d4",
      "partner": "usaa",
      "status": "completed",
      "original_filename": "enrollment_20250109.csv",
      "uploaded_at": "2025-01-09T14:30:00Z",
      "completed_at": "2025-01-09T14:37:23Z",
      "stats": {
        "total_rows": 2047,
        "valid_rows": 2041,
        "error_rows": 6
      },
      "download_url": "/download/run_a1b2c3d4",
      "errors_url": "/errors/run_a1b2c3d4"
    }
  ]
}

Download Completed File

GET /download/{run_id}

Download the normalized, validated enrollment file after processing completes.

Recommended Polling Strategy

• Initial polling: Every 10 seconds for first 2 minutes after upload
• Extended polling: Every 30 seconds for next 10 minutes
• Timeout: Consider file failed if not completed within 15 minutes
• Exponential backoff: Increase interval if status hasn't changed

Note: Webhooks are strongly recommended for production use as they provide immediate notifications and reduce API calls.

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

HTTP Status Codes

Code	Description
200	Success
201	Created (file uploaded successfully)
400	Bad Request (invalid parameters)
401	Unauthorized (invalid or missing token)
404	Not Found (job or resource doesn't exist)
429	Too Many Requests (rate limit exceeded)
500	Internal Server Error

Error Response Format

{
  "error": {
    "code": "invalid_file_format",
    "message": "File format could not be determined",
    "details": "Expected CSV, Excel, or EDI 834 format",
    "request_id": "req_xyz789",
    "documentation_url": "https://docs.strataweave.com/errors/invalid_file_format"
  }
}

Rate Limiting

API requests are limited to 1000 requests per hour per API key. Rate limit information is included in response headers.

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1704816000

SDK & Code Examples

Python

import requests

# Authenticate
auth_response = requests.post(
    'https://api.strataweave.com/v1/oauth/token',
    json={
        'grant_type': 'client_credentials',
        'client_id': 'your_client_id',
        'client_secret': 'your_client_secret'
    }
)
token = auth_response.json()['access_token']

# Upload file
with open('enrollment_data.csv', 'rb') as f:
    upload_response = requests.post(
        'https://api.strataweave.com/v1/files/upload',
        headers={'Authorization': f'Bearer {token}'},
        files={'file': f}
    )

job_id = upload_response.json()['job_id']
print(f"Job ID: {job_id}")

# Check status
status_response = requests.get(
    f'https://api.strataweave.com/v1/jobs/{job_id}',
    headers={'Authorization': f'Bearer {token}'}
)
print(status_response.json())

JavaScript / Node.js

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

// Authenticate
const authResponse = await axios.post(
  'https://api.strataweave.com/v1/oauth/token',
  {
    grant_type: 'client_credentials',
    client_id: 'your_client_id',
    client_secret: 'your_client_secret'
  }
);
const token = authResponse.data.access_token;

// Upload file
const form = new FormData();
form.append('file', fs.createReadStream('enrollment_data.csv'));

const uploadResponse = await axios.post(
  'https://api.strataweave.com/v1/files/upload',
  form,
  {
    headers: {
      ...form.getHeaders(),
      'Authorization': `Bearer ${token}`
    }
  }
);

const jobId = uploadResponse.data.job_id;
console.log(`Job ID: ${jobId}`);

cURL

# Authenticate
curl -X POST https://api.strataweave.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

# Upload file
curl -X POST https://api.strataweave.com/v1/files/upload \
  -H "Authorization: Bearer {token}" \
  -F "file=@enrollment_data.csv"

# Check status
curl -X GET https://api.strataweave.com/v1/jobs/{job_id} \
  -H "Authorization: Bearer {token}"

Webhook Handler Example (Node.js + Express)

const express = require('express');
const crypto = require('crypto');
const axios = require('axios');

const app = express();
app.use(express.json());

// Webhook endpoint
app.post('/webhooks/strataweave', async (req, res) => {
  // Verify signature
  const signature = req.headers['x-strataweave-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(JSON.stringify(req.body)).digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest))) {
    return res.status(401).send('Invalid signature');
  }

  // Handle completed job
  const { event, job_id, status, download_urls } = req.body;

  if (event === 'job.completed' && status === 'completed') {
    console.log(`File processing completed: ${job_id}`);

    // Download the normalized file
    const downloadResponse = await axios.get(download_urls.normalized_data, {
      headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
    });

    // Process the normalized data
    const enrollmentData = downloadResponse.data;
    console.log(`Received ${enrollmentData.records.length} records`);

    // Your business logic here...
  }

  res.status(200).send('OK');
});

app.listen(3000);

Polling Example (Node.js)

const axios = require('axios');

async function pollForCompletion(jobId, token) {
  const maxAttempts = 60; // 10 minutes with 10-second intervals
  const pollInterval = 10000; // 10 seconds

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const response = await axios.get(
        `https://api.strataweave.com/v1/jobs/${jobId}`,
        { headers: { 'Authorization': `Bearer ${token}` }}
      );

      const { status } = response.data;

      if (status === 'completed') {
        console.log('✓ Processing completed!');

        // Download the file
        const downloadUrl = response.data.download_url;
        const fileResponse = await axios.get(downloadUrl, {
          headers: { 'Authorization': `Bearer ${token}` }
        });

        return fileResponse.data;
      } else if (status === 'failed') {
        throw new Error('Processing failed');
      }

      console.log(`Status: ${status}. Waiting...`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));

    } catch (error) {
      console.error('Polling error:', error.message);
      throw error;
    }
  }

  throw new Error('Timeout: File processing took too long');
}

// Usage
const data = await pollForCompletion('job_abc123', 'your_token_here');

Support

For API support, technical questions, or to report issues:

• Email: [email protected]
• Documentation: docs.strataweave.com
• Status Page: status.strataweave.com