Skip to content

Tax Practice AI - Integration Contracts

Version: 1.0 Last Updated: 2024-12-23 Status: Draft

Table of Contents

  1. Overview
  2. SmartVault Integration
  3. SurePrep Integration
  4. UltraTax CS Integration
  5. Stripe Integration
  6. Persona Integration
  7. Google Workspace Integration
  8. E-Filing Transmitter Integration
  9. AWS Internal Services
  10. Email and SMS Integration
Document Purpose
ARCHITECTURE.md Service patterns, data flow diagrams
API_SPECIFICATION.md Our API endpoints including webhook handlers
SECURITY_DESIGN.md Authentication, encryption requirements
src/ai/skills/integrations/ AI skill documentation for integrations

1. Overview

1.1 Integration Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                           TAX PRACTICE AI                                │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     Integration Layer                             │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐ │   │
│  │  │ SmartVault │  │  SurePrep  │  │   Stripe   │  │  Persona   │ │   │
│  │  │  Service   │  │  Service   │  │  Service   │  │  Service   │ │   │
│  │  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘ │   │
│  │        │               │               │               │        │   │
│  │  ┌─────┴───────────────┴───────────────┴───────────────┴──────┐ │   │
│  │  │                  Service Registry                           │ │   │
│  │  └─────────────────────────────────────────────────────────────┘ │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
         │              │              │              │
         ▼              ▼              ▼              ▼
    ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
    │SmartVault│  │ SurePrep │  │  Stripe  │  │ Persona  │
    │   API   │   │   API   │   │   API   │   │   API   │
    └─────────┘   └─────────┘   └─────────┘   └─────────┘

1.2 Integration Summary

Integration Purpose Auth Method Data Flow
SmartVault Client document portal OAuth 2.0 Bidirectional
SurePrep Document OCR/extraction Basic + API Key Bidirectional
UltraTax CS Tax software Via SurePrep One-way (out)
Stripe Payment processing API Key Webhooks in
Persona Identity verification API Key Bidirectional
Google Workspace E-signatures, Meet OAuth 2.0 Bidirectional
E-Filing Transmitter IRS/State filing API Key Bidirectional
AWS S3 Document storage IAM Internal
AWS Bedrock AI (Claude) IAM Internal
AWS SES Email IAM Outbound
Twilio SMS/Voice API Key Outbound

1.3 Common Integration Patterns

Retry Strategy: 

# Exponential backoff with jitter
def retry_with_backoff(func, max_retries=3, base_delay=1.0):
    for attempt in range(max_retries):
        try:
            return func()
        except RetryableError as e:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Circuit Breaker: - Open after 5 consecutive failures - Half-open after 30 seconds - Close after 3 successful requests

Timeout Policy: - Connection timeout: 10 seconds - Read timeout: 30 seconds (60 for file uploads)

2. SmartVault Integration

2.1 Overview

Attribute Value
Purpose Client document portal for uploads and deliveries
Base URL https://rest.smartvault.com
Documentation https://developer.smartvault.com/
Auth Method OAuth 2.0 (server-to-server)
Response Format JSON (requires Accept: application/json header)

2.2 Authentication

OAuth 2.0 Server-to-Server Flow:

1. Generate RSA keypair
2. Register public key with SmartVault
3. Create JWT signed with private key
4. Exchange JWT for access token
5. Use access token for API requests

Token Request: 

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id={client_id}
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion={signed_jwt}

Token Response: 

{
  "access_token": "eyJhbGciOiJSUzI1NiI...",
  "token_type": "bearer",
  "expires_in": 3600
}

Token Refresh: Tokens expire in 1 hour; re-authenticate before expiry.

2.3 Key Endpoints

List Folder Contents

GET /nodes/pth/{path}?children=1
Authorization: Bearer {access_token}
Accept: application/json

Path Examples: - /clients/JohnSmith/Tax Year 2024/Source Documents - /clients/JohnSmith/Tax Year 2024/Completed Returns

Response: 

{
  "name": "Source Documents",
  "uri": "/nodes/pth/clients/JohnSmith/Tax Year 2024/Source Documents",
  "children": [
    {
      "name": "W-2_Employer.pdf",
      "doc_id": "doc-123",
      "size": 125000,
      "modified": "2024-12-20T10:00:00Z",
      "download_uri": "/files/id/Document/doc-123"
    }
  ]
}

Download Document

GET /files/id/Document/{doc_id}
Authorization: Bearer {access_token}

Response: Binary file content

Upload Document (3-Step)

Step 1: Create file metadata 

PUT /nodes/pth/{folder_path}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "create_file": [{"name": "Return_2024_Final.pdf"}]
}

Step 2: Initialize upload 

PUT /nodes/upload/{file_id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "length": 1250000,
  "md5_checksum": "abc123..."
}

Step 3: Upload content 

PUT /nodes/upload/{file_id}/{doc_version_id}
Authorization: Bearer {access_token}
Content-Type: application/binary

<binary file data>

Create Folder

PUT /nodes/pth/{parent_path}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "create_folder": [{"name": "Tax Year 2024"}]
}

2.4 Webhook Events

Event Trigger Our Action
document.uploaded Client uploads document Queue for processing
folder.created New client folder created Sync client record

Webhook Payload: 

{
  "event": "document.uploaded",
  "account_id": "account-123",
  "path": "/clients/JohnSmith/Tax Year 2024/Source Documents",
  "file_name": "W-2_Employer.pdf",
  "doc_id": "doc-456",
  "uploaded_at": "2024-12-23T10:00:00Z"
}

2.5 Error Codes

Code Meaning Retry
400 Invalid parameters No
401 Auth failed Re-authenticate
403 Permission denied No
404 Path not found No
409 Conflict (file exists) No
429 Rate limited Yes (backoff)
500 Server error Yes

2.6 Data Mappings

SmartVault Path → Our Data:

SmartVault Path Pattern Our Entity
/clients/{name} client.name
/clients/{name}/Tax Year {year} tax_return.tax_year
/clients/{name}/Tax Year {year}/Source Documents Document uploads
/clients/{name}/Tax Year {year}/Completed Returns Final deliverables

2.7 Rate Limits

Not explicitly documented. Implement: - Max 10 requests/second - Exponential backoff on 429

3. SurePrep Integration

3.1 Overview

Attribute Value
Purpose Document OCR, data extraction, UltraTax bridge
Base URL https://api.sureprep.com/api/v1/
Documentation https://developer.sureprep.com/
Auth Method HTTP Basic + API Key
Products 1040SCAN, TaxCaddy, SPbinder, CS Connect

3.2 Authentication

Headers: 

Authorization: Basic {base64(username:password)}
X-API-Key: {api_key}

Setup Requirements: 1. API credentials configured in SurePrep FileRoom 2. API key generated from FileRoom integration settings 3. IP whitelist registration (required)

3.3 Key Endpoints

Create Binder

POST /binders
Content-Type: application/json

{
  "client_id": "our-client-uuid",
  "tax_year": 2024,
  "return_type": "1040",
  "client_name": "John Smith",
  "preparer_id": "preparer-uuid"
}

Response: 

{
  "binder_id": "BND-2024-00123",
  "status": "created",
  "created_at": "2024-12-23T10:00:00Z"
}

Upload Document to Binder

POST /binders/{binder_id}/documents
Content-Type: multipart/form-data

file: <binary PDF/image>
document_type: "W-2"  (optional - auto-detected)

Response: 

{
  "doc_id": "DOC-001",
  "filename": "W-2_employer.pdf",
  "document_type": "W-2",
  "status": "uploaded",
  "pages": 1
}

Submit Binder for Processing

POST /binders/{binder_id}/submit

Triggers OCR and extraction. Returns immediately; use webhooks for completion.

Get Binder Status

GET /binders/{binder_id}

Response: 

{
  "binder_id": "BND-2024-00123",
  "status": "verified",
  "documents": [
    {"doc_id": "DOC-001", "type": "W-2", "status": "verified"},
    {"doc_id": "DOC-002", "type": "1099-INT", "status": "verified"}
  ],
  "extraction_status": "complete"
}

Get Extracted Data

GET /binders/{binder_id}/extracted-data

Response: 

{
  "binder_id": "BND-2024-00123",
  "extraction_status": "complete",
  "documents": [
    {
      "doc_id": "DOC-001",
      "document_type": "W-2",
      "confidence": 0.95,
      "is_native_pdf": true,
      "fields": [
        {
          "field": "employer_ein",
          "value": "12-3456789",
          "box": "b",
          "confidence": 0.99,
          "verified": true,
          "source": "auto"
        },
        {
          "field": "wages",
          "value": "85000.00",
          "box": "1",
          "confidence": 0.97,
          "verified": true,
          "source": "auto"
        }
      ]
    }
  ]
}

3.4 Webhook Events

Configure webhook URL in SurePrep FileRoom.

Event Trigger Our Action
binder.submitted Binder submitted Log, update status
binder.processing_complete OCR finished Fetch extracted data
binder.verification_complete Manual verification done Update confidence
document.uploaded Document added Sync document list
extraction.ready Extracted data available Import extraction results

Webhook Payload: 

{
  "event": "binder.processing_complete",
  "binder_id": "BND-2024-00123",
  "timestamp": "2024-12-23T12:00:00Z",
  "data": {
    "status": "complete",
    "documents_processed": 5,
    "overall_confidence": 0.92
  }
}

Webhook Signature: SurePrep signs webhooks with HMAC-SHA256. Verify before processing.

3.5 Status Values

Binder Status:

Status Description
created Binder created, no documents
uploading Documents being added
submitted Submitted for processing
processing OCR/extraction in progress
pending_review Awaiting manual verification
verified All documents verified
exported Data exported to tax software
complete Workflow complete

Document Status:

Status Description
uploaded Document received
processing OCR in progress
pending_review Needs manual verification
verified Extraction verified
error Processing failed

3.6 Confidence Scoring

Score Range Interpretation Action
95-100% High confidence Auto-verify
85-94% Good confidence Spot check
70-84% Medium confidence Manual review
<70% Low confidence Full review

Fields requiring extra scrutiny: - Dollar amounts (OCR errors common) - Handwritten entries (low accuracy) - K-1 footnotes (non-standardized) - State-specific forms

3.7 Data Mappings

SurePrep Field → Our Schema:

SurePrep Field Document Type Our Field
employer_ein W-2 extracted_field.value where field_name='employer_ein'
wages W-2 extracted_field.value where field_name='box_1_wages'
payer_name 1099-INT extracted_field.value where field_name='payer_name'
interest_income 1099-INT extracted_field.value where field_name='box_1_interest'

3.8 Rate Limits

Recommended limits (not explicitly documented): - Max 10 requests/second - Batch document uploads where possible - Use webhooks instead of polling

3.9 Error Handling

Code Meaning Retry
400 Invalid parameters No
401 Invalid credentials No
403 IP not whitelisted No
404 Binder/document not found No
429 Rate limited Yes
500 Server error Yes

4. UltraTax CS Integration

4.1 Overview

Attribute Value
Purpose Tax preparation software
Vendor Thomson Reuters
API Available No public API
Integration Method Via SurePrep CS Connect only

4.2 Integration Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Our System  │ ──► │  SurePrep   │ ──► │ UltraTax CS │
│             │     │  (API)      │     │ (No API)    │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    CS Connect
                  (Native Integration)

4.3 What We Can Do

Action Method
Send documents for extraction SurePrep API
Validate extracted data Our AI layer
Trigger UltraTax data population SurePrep CS Connect (automatic)

4.4 What We Cannot Do

Action Reason
Query UltraTax directly No API
Push data to UltraTax No API
Read return status from UltraTax No API
Modify UltraTax data No API

4.5 CS Connect Setup

Prerequisites (in UltraTax CS): 1. Setup → System Configuration 2. CS Connect tab → Enable CS Connect Background Services 3. Check "Enable SurePrep Integration" 4. Add integration, copy API key 5. Paste key in SurePrep Admin → Account Setup

4.6 Field Mapping Knowledge

We maintain field mapping knowledge for validation:

UltraTax Field Form Description
W2.1.WAGES W-2 Box 1 - Wages
W2.1.FWITHHELD W-2 Box 2 - Federal withholding
INT.1.AMOUNT 1099-INT Box 1 - Interest income
DIV.1A.ORDINARY 1099-DIV Box 1a - Ordinary dividends

See src/ai/skills/integrations/ultratax/field_mappings.md for complete list.

5. Stripe Integration

5.1 Overview

Attribute Value
Purpose Payment processing
Base URL https://api.stripe.com/v1
Documentation https://stripe.com/docs/api
Auth Method API Key (Bearer token)

5.2 Authentication

Authorization: Bearer sk_live_xxxxx

Keys: - sk_live_* - Production secret key - sk_test_* - Test mode secret key - Store in AWS Secrets Manager

5.3 Key Endpoints

POST /v1/payment_links
Content-Type: application/x-www-form-urlencoded

line_items[0][price_data][currency]=usd
line_items[0][price_data][product_data][name]=2024 Tax Return Preparation
line_items[0][price_data][unit_amount]=45000
line_items[0][quantity]=1
metadata[invoice_id]=inv-uuid
metadata[client_id]=client-uuid

Response: 

{
  "id": "plink_xxxxx",
  "url": "https://buy.stripe.com/xxxxx",
  "active": true
}

Create Payment Intent

POST /v1/payment_intents
Content-Type: application/x-www-form-urlencoded

amount=45000
currency=usd
metadata[invoice_id]=inv-uuid

Retrieve Payment Intent

GET /v1/payment_intents/{payment_intent_id}

5.4 Webhook Events

Configure webhook endpoint in Stripe Dashboard.

Critical Events:

Event Trigger Our Action
payment_intent.succeeded Payment successful Mark invoice paid
payment_intent.payment_failed Payment failed Notify client
checkout.session.completed Payment link used Mark invoice paid

Webhook Payload: 

{
  "id": "evt_xxxxx",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_xxxxx",
      "amount": 45000,
      "currency": "usd",
      "status": "succeeded",
      "metadata": {
        "invoice_id": "inv-uuid",
        "client_id": "client-uuid"
      }
    }
  }
}

5.5 Webhook Signature Verification

import stripe

def verify_stripe_webhook(payload: bytes, sig_header: str, secret: str):
    try:
        event = stripe.Webhook.construct_event(payload, sig_header, secret)
        return event
    except stripe.error.SignatureVerificationError:
        raise InvalidSignatureError()

5.6 Pricing

Method Fee
Credit Card 2.9% + $0.30
ACH 0.8% (capped at $5)

6. Persona Integration

6.1 Overview

Attribute Value
Purpose Identity verification (government ID)
Base URL https://withpersona.com/api/v1
Documentation https://docs.withpersona.com/
Auth Method API Key

6.2 Authentication

Authorization: Bearer persona_api_key_xxxxx

6.3 Key Endpoints

Create Inquiry

POST /inquiries
Content-Type: application/json

{
  "data": {
    "type": "inquiry",
    "attributes": {
      "inquiry-template-id": "itmpl_xxxxx",
      "reference-id": "client-uuid"
    }
  }
}

Response: 

{
  "data": {
    "type": "inquiry",
    "id": "inq_xxxxx",
    "attributes": {
      "status": "created",
      "reference-id": "client-uuid",
      "meta": {
        "session-token": "session_xxxxx"
      }
    }
  }
}

Get Inquiry Status

GET /inquiries/{inquiry_id}

Response: 

{
  "data": {
    "type": "inquiry",
    "id": "inq_xxxxx",
    "attributes": {
      "status": "completed",
      "reference-id": "client-uuid",
      "verification-confidence": 0.92,
      "verification-status": "passed"
    },
    "relationships": {
      "verifications": {
        "data": [
          {"type": "verification/government-id", "id": "ver_xxxxx"}
        ]
      }
    }
  }
}

6.4 Webhook Events

Event Trigger Our Action
inquiry.completed Verification finished Update client status
inquiry.failed Verification failed Route to Tier 3
inquiry.expired Session expired Notify client to retry

Webhook Payload: 

{
  "data": {
    "type": "event",
    "id": "evt_xxxxx",
    "attributes": {
      "name": "inquiry.completed",
      "payload": {
        "data": {
          "type": "inquiry",
          "id": "inq_xxxxx",
          "attributes": {
            "status": "completed",
            "reference-id": "client-uuid"
          }
        }
      }
    }
  }
}

6.5 Confidence Score Interpretation

Score Status Our Action
≥90% passed Auto-verify (Tier 2 complete)
70-89% needs_review Staff review queue
<70% failed Route to Tier 3

6.6 Pricing

  • ~$2-5 per verification
  • Volume discounts available

7. Google Workspace Integration

7.1 Overview

Attribute Value
Purpose E-signatures, Meet, Calendar
Auth Method OAuth 2.0
Scopes Drive, Docs, Calendar, Meet

7.2 Services Used

Service Purpose
Google Drive Store signed documents
Google Docs Generate engagement letters
Google Slides/Sheets Generate forms
Google Calendar Schedule video verification
Google Meet Video verification calls

7.3 E-Signature Flow

Google Workspace provides e-signature functionality via Google Docs add-ons or custom implementation.

Flow: 1. Generate document from template (Google Docs API) 2. Add signature request (Google Workspace Add-on or embedded) 3. Send notification to signer 4. Receive completion webhook 5. Store signed document in Drive

7.4 OAuth 2.0 Setup

# Authorization request
GET https://accounts.google.com/o/oauth2/v2/auth
?client_id={client_id}
&redirect_uri={redirect_uri}
&response_type=code
&scope=https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/calendar
&access_type=offline

# Token exchange
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded

code={auth_code}
client_id={client_id}
client_secret={client_secret}
redirect_uri={redirect_uri}
grant_type=authorization_code

7.5 Key APIs

Create Calendar Event (Meet)

POST https://www.googleapis.com/calendar/v3/calendars/primary/events
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "summary": "Identity Verification - John Smith",
  "description": "Tier 3 identity verification video call",
  "start": {
    "dateTime": "2024-12-24T10:00:00-08:00"
  },
  "end": {
    "dateTime": "2024-12-24T10:30:00-08:00"
  },
  "attendees": [
    {"email": "client@example.com"}
  ],
  "conferenceData": {
    "createRequest": {
      "requestId": "unique-request-id",
      "conferenceSolutionKey": {"type": "hangoutsMeet"}
    }
  }
}

7.6 Webhook Events

Google Workspace push notifications for real-time updates.

Event Trigger Our Action
signature.completed Document signed Update signature status, notify preparer
signature.declined Signer declined Mark declined, create follow-up task
calendar.event.updated Meeting changed Sync meet session record

Note: Google uses push notifications via registered webhook URLs. Configure in Google Cloud Console.

8. E-Filing Transmitter Integration

8.1 Overview

Attribute Value
Purpose IRS/State electronic filing
Recommended Vendors Column Tax, April API
Auth Method API Key

Base URL: https://api.columntax.com/v1

Transmit Return

POST /transmissions
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "return_id": "our-return-uuid",
  "tax_year": 2024,
  "return_type": "1040",
  "jurisdiction": "federal",
  "xml_data": "<Return>...</Return>",
  "signature": {
    "form_8879": {
      "signed_at": "2024-12-23T10:00:00Z",
      "pin": "12345"
    }
  }
}

Response: 

{
  "transmission_id": "trans-xxxxx",
  "status": "transmitted",
  "submitted_at": "2024-12-23T12:00:00Z"
}

Poll Acknowledgement

GET /transmissions/{transmission_id}/acknowledgement

Response (Accepted): 

{
  "transmission_id": "trans-xxxxx",
  "status": "accepted",
  "acknowledgement": {
    "confirmation_number": "IRS123456789",
    "accepted_at": "2024-12-23T15:30:00Z"
  }
}

Response (Rejected): 

{
  "transmission_id": "trans-xxxxx",
  "status": "rejected",
  "rejections": [
    {
      "error_code": "IND-031-04",
      "category": "data_mismatch",
      "description": "SSN/Name mismatch with SSA records",
      "field_path": "Return.Filer.SSN"
    }
  ]
}

8.3 Rejection Categories

Category Description Auto-Correctable
data_mismatch Data doesn't match IRS records Sometimes
missing_info Required field missing Yes
duplicate Return already filed No (fraud review)
technical Schema/format error Yes
business_rule IRS rule violation No

8.4 Webhook Events

Event Trigger Our Action
transmission.accepted IRS accepted Update status, notify client
transmission.rejected IRS rejected Parse errors, route to preparer
transmission.pending Still processing Wait

8.5 Polling Strategy

During filing season: - Poll every 6 hours for pending transmissions - Immediate poll when webhook received

9. AWS Internal Services

9.1 S3 (Document Storage)

Bucket Purpose Lifecycle
tax-practice-documents-{env} Active documents Standard → IA (1yr) → Glacier (3yr)
tax-practice-archive-{env} Long-term archive Glacier

Key Structure: 

s3://tax-practice-documents-prod/
├── clients/{client_id}/
│   └── {tax_year}/
│       └── {document_type}_{timestamp}.pdf
├── returns/{return_id}/
│   └── final_return_{timestamp}.pdf
└── temp/
    └── {upload_id}/

Encryption: SSE-KMS (AES-256)

9.2 Bedrock (Claude AI)

Model: Claude 3 Sonnet (claude-3-sonnet-20240229)

Usage: 

import boto3

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

response = bedrock.invoke_model(
    modelId='anthropic.claude-3-sonnet-20240229-v1:0',
    contentType='application/json',
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 4096,
        "messages": [
            {"role": "user", "content": prompt}
        ]
    })
)

Cost Optimization: - Use Haiku for simple tasks - Use Sonnet for document analysis - Use Opus for complex reasoning - Batch API for non-urgent work (50% savings)

9.3 KMS (Key Management)

Keys: - alias/tax-practice-db - Database encryption - alias/tax-practice-s3 - S3 encryption - alias/tax-practice-field - Field-level encryption

10. Email and SMS Integration

10.1 AWS SES (Email)

Region: us-east-1

Configuration: - Verified domain: taxpractice.example.com - DKIM enabled - SPF configured - DMARC policy in place

Sending: 

import boto3

ses = boto3.client('ses', region_name='us-east-1')

ses.send_email(
    Source='noreply@taxpractice.example.com',
    Destination={
        'ToAddresses': ['client@example.com']
    },
    Message={
        'Subject': {'Data': 'Your 2024 Tax Return is Ready'},
        'Body': {
            'Html': {'Data': html_content}
        }
    }
)

10.2 Twilio (SMS/Voice)

Base URL: https://api.twilio.com/2010-04-01

Authentication: 

Authorization: Basic {base64(account_sid:auth_token)}

Send SMS

POST /Accounts/{account_sid}/Messages.json

To=+15551234567
From=+15559876543
Body=Your verification code is 123456

Send Voice Call

POST /Accounts/{account_sid}/Calls.json

To=+15551234567
From=+15559876543
Url=https://api.taxpractice.example.com/twilio/voice/verify

TwiML for Voice: 

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="alice">
        Your verification code is 1 2 3 4 5 6.
        I repeat, your code is 1 2 3 4 5 6.
    </Say>
</Response>

Pricing: - SMS: $0.0075/message - Voice: ~$0.015/minute

Appendix A: Environment Configuration

A.1 Configuration Template

# config.yaml - Integration credentials from environment/secrets

# =============================================================================
# SMARTVAULT
# =============================================================================
smartvault:
  # base_url: SmartVault REST API endpoint
  base_url: https://rest.smartvault.com

  # client_id: OAuth client ID from developer portal
  client_id: ${SMARTVAULT_CLIENT_ID}

  # private_key_path: Path to RSA private key for OAuth
  private_key_path: ${SMARTVAULT_PRIVATE_KEY_PATH}

  # account_id: SmartVault account identifier
  account_id: ${SMARTVAULT_ACCOUNT_ID}

# =============================================================================
# SUREPREP
# =============================================================================
sureprep:
  # base_url: SurePrep API endpoint
  base_url: https://api.sureprep.com/api/v1

  # username: API username from FileRoom
  username: ${SUREPREP_USERNAME}

  # password: API password
  password: ${SUREPREP_PASSWORD}

  # api_key: API key from FileRoom integration settings
  api_key: ${SUREPREP_API_KEY}

# =============================================================================
# STRIPE
# =============================================================================
stripe:
  # api_key: Stripe secret key (sk_live_* or sk_test_*)
  api_key: ${STRIPE_API_KEY}

  # webhook_secret: Webhook signing secret
  webhook_secret: ${STRIPE_WEBHOOK_SECRET}

# =============================================================================
# PERSONA
# =============================================================================
persona:
  # api_key: Persona API key
  api_key: ${PERSONA_API_KEY}

  # template_id: Inquiry template ID
  template_id: ${PERSONA_TEMPLATE_ID}

  # webhook_secret: Webhook signing secret
  webhook_secret: ${PERSONA_WEBHOOK_SECRET}

# =============================================================================
# E-FILING
# =============================================================================
efiling:
  # provider: Transmitter provider (column_tax, april)
  provider: column_tax

  # base_url: Transmitter API endpoint
  base_url: https://api.columntax.com/v1

  # api_key: Transmitter API key
  api_key: ${EFILING_API_KEY}

# =============================================================================
# TWILIO
# =============================================================================
twilio:
  # account_sid: Twilio account SID
  account_sid: ${TWILIO_ACCOUNT_SID}

  # auth_token: Twilio auth token
  auth_token: ${TWILIO_AUTH_TOKEN}

  # phone_number: Twilio phone number for SMS/calls
  phone_number: ${TWILIO_PHONE_NUMBER}

Appendix B: Health Check Endpoints

Each integration should implement health checks:

def health_check_integrations():
    results = {}

    # SmartVault
    try:
        services.smartvault.get_account_info()
        results['smartvault'] = {'status': 'healthy'}
    except Exception as e:
        results['smartvault'] = {'status': 'unhealthy', 'error': str(e)}

    # SurePrep
    try:
        services.sureprep.ping()
        results['sureprep'] = {'status': 'healthy'}
    except Exception as e:
        results['sureprep'] = {'status': 'unhealthy', 'error': str(e)}

    # ... other integrations

    return results

Document History

Version Date Author Changes
1.0 2024-12-23 Don McCarty Initial integration contracts document

This document defines integration contracts for Tax Practice AI. Implementations must follow these specifications to ensure reliable external system communication.