05 API Integrations

Integrations and API Guide

Doc status: Refer to the OpenAPI spec for current endpoints (some routes pending). See Reality Index: reality.md.

Overview

The Integrations system connects your notarial platform with external services across multiple categories and providers. Availability varies by environment and feature flags. This system follows a "thin API, blackbox" architecture pattern, with clean separation between integration setup (in the Integrations module) and actual communication actions (in Communications module).

Integration Categories

1. Email Integrations

Connect your existing email accounts to send communications through your preferred provider:

Gmail: Use your Gmail or Google Workspace account
Outlook: Connect with Microsoft 365 or Exchange
Custom SMTP: Configure your own SMTP server

2. Messaging Integrations

Set up multiple messaging channels for instant client communication:

Twilio SMS: SMS messaging with global reach
WhatsApp Business: Rich messaging on the world's most popular messaging app
MMS: Picture and video messaging support
Slack: Internal team communications

3. Calendar Integrations

Synchronize appointments across your calendar systems:

Google Calendar: Two-way sync with Google Calendar
Outlook Calendar: Connect with Microsoft Exchange and Office 365
CalDAV: Support for any CalDAV-compatible calendar

4. CRM Integrations

Keep customer data synchronized across your CRM:

Salesforce: World's leading CRM with custom objects
HubSpot: All-in-one marketing, sales, and service platform
Zoho CRM: Complete business management suite

5. Accounting Integrations

Automate financial management and reporting:

QuickBooks: Most popular accounting software for small businesses
Xero: Cloud-based accounting with powerful features
FreshBooks: Simple accounting for freelancers and small businesses
Sage: Enterprise-grade accounting solution
Wave: Free accounting software with basic features

6. Payment Integrations

Accept online payments securely (status):

Stripe: Live
PayPal: Partial
Dwolla: Connect-only

7. E-Check Integrations

Process electronic checks for lower transaction fees:

Plaid: Bank account verification and ACH processing
Stripe ACH: ACH payments through your Stripe account
Dwolla: Dedicated ACH payment platform

8. API Keys

Generate secure API keys for client and partner access:

Custom API Access: REST APIs with authentication (see OpenAPI; some routes pending)
Webhook Support: Real-time notifications for events
Rate Limiting: Configurable limits for each key
Usage Analytics: Track API usage and performance

Quick Start
Accessing Integrations
API Management
Integration Setup
Webhook Configuration
Authentication
Rate Limiting
Security Best Practices
Troubleshooting

Quick Start

Setting Up Your First Integration

Navigate to Integrations:
- Dashboard → Settings → Integrations
Choose Your Category:
- Click on the appropriate tab (Email, Messaging, Calendar, etc.)
Select a Provider:
- Review features and setup time
- Click "Connect" or "Configure"
Complete Authentication:
- OAuth: Click "Connect" and follow provider prompts
- API Key: Copy credentials from provider dashboard
Configure Settings:
- Select sync options
- Set up notifications
- Test connection

Accessing Integrations

The Integrations Dashboard provides a centralized interface for managing all your connections:

Dashboard Location: Settings → Integrations
Eight Integration Tabs: One for each category
Status Indicators:
- Green = Active and healthy
- Yellow = Warnings or issues
- Red = Connection failed
Quick Actions: Test sync, view logs, run diagnostics

Integration Cards

Each provider is displayed as a card showing:

Provider logo and name
Key features (3-4 bullet points)
Setup complexity (2-30 minutes)
Pricing information
Connection status

API Management

Accessing API Settings

Go to Dashboard → Agency → Settings → API Keys tab
View existing API keys and their usage
Generate new API keys as needed
Manage OAuth clients

Generating API Keys

Create New Key:
- Click "Generate New API Key"
- Enter a descriptive name (e.g., "Mobile App Integration")
- Select scopes (read, write, delete, admin)
- Set expiration (optional)
- Click "Generate"

Key Information:

API Key: notary_abc123def456...
Description: Mobile App Integration
Scopes: read, write
Created: 2024-01-15
Last Used: 2024-01-20
Expires: Never

Key Scopes:
- read: View data (customers, orders, invoices, notaries)
- write: Create and modify data
- delete: Delete records
- admin: Full access including settings and user management

Key Format:

Format: notary_<random_32_characters>
Example: notary_xK9mP2vR4nQ8sT6wY1hJ3fD5cZ7bN9

Managing OAuth Clients

Create OAuth Client:
- Navigate to Integrations → OAuth tab
- Click "Create OAuth Client"
- Enter name and description
- Select allowed scopes
- Save credentials (secret shown only once!)

OAuth Client Properties:

Client ID: client_abc123xyz
Client Secret: [shown only at creation]
Grant Types: client_credentials
Status: Active/Inactive
Last Used: [timestamp]

View Access Tokens:
- See all active tokens for a client
- Revoke compromised tokens
- Monitor token usage

API Key Security

Hashing: Keys are SHA-256 hashed before storage
Rotation: Regularly rotate keys for security
Revocation: Revoke compromised keys immediately
Scoped Access: Limit keys to specific functionality
Audit Trail: All API usage logged via audit_log table

API Endpoints

Authentication

POST /api/auth/login
Headers: {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Orders

GET /api/orders           # List orders
POST /api/orders          # Create order
GET /api/orders/{id}      # Get specific order
PUT /api/orders/{id}      # Update order

Customers

GET /api/customers         # List customers
POST /api/customers        # Create customer
GET /api/customers/{id}    # Get customer
PUT /api/customers/{id}    # Update customer

Invoices

GET /api/invoices          # List invoices
POST /api/invoices         # Create invoice
GET /api/invoices/{id}     # Get invoice
POST /api/invoices/{id}/pay # Record payment

Integration Setup

Authentication Methods

OAuth 2.0 (Recommended)

Used by most modern services for secure, token-based authentication:

Google: Gmail, Calendar, Drive
Microsoft: Outlook, Office 365
Salesforce: CRM integration
QuickBooks: Accounting integration

Benefits:

No need to store passwords
Tokens can be revoked anytime
Scoped permissions (least privilege)
Automatic token refresh

API Key Authentication

Used by services that don't support OAuth:

Twilio: SMS and messaging
SendGrid: Email service
Stripe: Payment processing
Custom SMTP: Email servers

Best Practices:

Store keys securely (encrypted at rest)
Rotate keys regularly
Use environment variables in development
Limit key scope and permissions

Category-Specific Setup

Email Integrations

Setup Time: 2-5 minutes Common Configuration:

OAuth (Gmail/Outlook) or API keys (SendGrid)
Default from address and reply-to
Signature templates
Delivery tracking settings

Messaging Integrations

Setup Time: 5-15 minutes Requirements:

Verified phone number (SMS)
Business account (WhatsApp)
Webhook URLs for inbound messages
Consent management for compliance

Calendar Integrations

Setup Time: 3-5 minutes Sync Options:

Two-way synchronization
Conflict resolution rules
Booking window settings
Team calendar sharing

CRM Integrations

Setup Time: 10-20 minutes Field Mapping:

Client information
Communication history
Order data
Custom field synchronization

Accounting Integrations

Setup Time: 10-30 minutes Data Sync:

Invoices and payments
Customer records
Expense categories
Tax mappings

Google Workspace Integration

Google Calendar:

Client ID: your_google_client_id
Client Secret: [encrypted]
Scopes: calendar.readonly, calendar.events

Google Drive:

Client ID: your_google_client_id
Client Secret: [encrypted]
Scopes: drive.readonly, drive.file

Gmail:

Client ID: your_google_client_id
Client Secret: [encrypted]
Scopes: gmail.send, gmail.readonly

Payment Gateway Integration

Stripe Configuration

Publishable Key: pk_live_1234567890abcdef...
Secret Key: [encrypted]
Webhook Secret: [encrypted]
Environment: Production

PayPal Configuration

Client ID: your_paypal_client_id
Client Secret: [encrypted]
Environment: Live/Sandbox
Webhook ID: your_webhook_id

Dwolla Configuration

API Key: your_dwolla_api_key
API Secret: [encrypted]
Environment: Production
Webhook URL: https://yourapp.com/api/integrations/dwolla/webhook

DocuSign Integration

Integration Key: your_docusign_integration_key
User GUID: your_user_guid
Account ID: your_account_id
Base URL: https://www.docusign.net

Email Service Integration

SendGrid

API Key: [encrypted]
From Email: noreply@yournotary.com
Templates: Enabled
Tracking: Opens, Clicks, Unsubscribes

Mailgun

API Key: [encrypted]
Domain: mail.yournotary.com
Region: US
Webhook Signing Key: [encrypted]

Webhook Configuration

Creating Webhooks

Navigate to Webhooks:
- Settings → API → Webhooks
- Click "Add Webhook"

Webhook Configuration:

URL: https://yourapp.com/webhooks/notarial
Events: order.created, payment.completed, invoice.generated
Secret: your_webhook_secret
Active: Yes

Supported Events

Order Events

order.created: New order created
order.updated: Order details changed
order.completed: Order marked complete
order.cancelled: Order cancelled

Payment Events

payment.initiated: Payment started
payment.completed: Payment successful
payment.failed: Payment failed
payment.refunded: Refund processed

Customer Events

customer.created: New customer registered
customer.updated: Profile updated
customer.deleted: Account deleted

Invoice Events

invoice.generated: Invoice created
invoice.sent: Invoice delivered
invoice.paid: Invoice paid
invoice.overdue: Invoice overdue

Webhook Payload Example

{
  "event": "order.created",
  "data": {
    "orderId": "ord_123456",
    "customerId": "cust_7890",
    "amount": 150.0,
    "currency": "USD",
    "status": "pending",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "timestamp": "2024-01-15T10:30:01Z",
  "signature": "sha256=abcdef1234567890..."
}

Verifying Webhooks

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

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto.createHmac("sha256", secret).update(payload).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(`sha256=${expectedSignature}`), Buffer.from(signature));
}

Authentication

The Notarial API supports three authentication methods:

1. API Key Authentication (Recommended for Simple Integrations)

Use an API key for straightforward integrations. Keys are scoped to specific permissions.

X-API-Key: notary_abc123def456...

Example Request:

GET /api/orders
X-API-Key: notary_abc123def456...
Content-Type: application/json

2. OAuth 2.0 Client Credentials (Recommended for Server-to-Server)

Use OAuth 2.0 client credentials flow for machine-to-machine authentication with better security and token management.

Step 1: Obtain Client Credentials

Contact your agency administrator to create OAuth credentials, or generate them from the Integrations dashboard:

Client ID: Your OAuth client identifier
Client Secret: Your secret key (shown only once)

Step 2: Request Access Token

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

grant_type=client_credentials&
client_id=your_client_id&
client_secret=your_client_secret&
scope=read write

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write",
  "created_at": "2024-01-15T10:30:00Z"
}

Step 3: Use Access Token

GET /api/orders
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Token Lifetime: 1 hour (renew as needed)

3. Session Authentication (For Web Applications)

For web applications, use session-based authentication via cookies. First authenticate via the web login, then use the session cookie for API requests.

GET /api/orders
Cookie: next-auth.session-token=your_session_token

Creating OAuth Clients

Via Dashboard

Navigate to Agency → Settings → Integrations → OAuth
Click "Create OAuth Client"
Enter:
- Name: Descriptive name (e.g., "Mobile App Backend")
- Scopes: Select permissions (read, write, delete, admin)
Save credentials - secret shown only once!

Via API

POST /api/integrations/oauth/clients
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{
  "name": "Production API Client",
  "description": "Client for production mobile app",
  "scopes": ["read", "write"]
}

Response:

{
  "id": 1,
  "clientId": "client_abc123xyz",
  "clientSecret": "secret_xyz789abc", // Store securely!
  "name": "Production API Client",
  "scopes": ["read", "write"],
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Rate Limiting

Rate Limit Tiers

Plan	Requests/Hour	Burst Limit
Basic	1,000	100
Professional	10,000	500
Enterprise	100,000	2,000

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642694400

Handling Rate Limits

// Exponential backoff implementation
async function makeRequest(url, options, retries = 3) {
  try {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After")) || 60;

      if (retries > 0) {
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
        return makeRequest(url, options, retries - 1);
      }
    }

    return response;
  } catch (error) {
    if (retries > 0) {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      return makeRequest(url, options, retries - 1);
    }
    throw error;
  }
}

Security Best Practices

API Key Management

Environment Variables:

NOTARIAL_API_KEY=sk_live_1234567890abcdef...
NOTARIAL_WEBHOOK_SECRET=whsec_1234567890abcdef...

Key Rotation Schedule:
- Production keys: Every 90 days
- Development keys: Every 30 days
- Compromised keys: Immediately
Access Patterns:
- Use scoped keys for specific applications
- Implement principle of least privilege
- Regular audit of key usage

Webhook Security

HTTPS Only: Always use HTTPS endpoints
Signature Verification: Verify all webhook signatures
Replay Protection: Use unique IDs to prevent replay attacks
IP Whitelisting: Restrict webhook calls to known IPs

Data Handling

Encryption: All sensitive data encrypted in transit
Sanitization: Sanitize all input data
Validation: Validate API responses
Logging: Log all API calls for audit

SDKs and Libraries

Official SDKs

JavaScript/Node.js

npm install @notarial/api

import { NotarialAPI } from "@notarial/api";

const client = new NotarialAPI({
  apiKey: process.env.NOTARIAL_API_KEY,
  environment: "production",
});

const orders = await client.orders.list({ limit: 10 });

Python

pip install notarial-python

from notarial import NotarialAPI

client = NotarialAPI(
    api_key='sk_live_1234567890abcdef...',
    environment='production'
)

orders = client.orders.list(limit=10)

PHP

composer require notarial/php

use Notarial\NotarialAPI;

$client = new NotarialAPI([
    'api_key' => 'sk_live_1234567890abcdef...',
    'environment' => 'production'
]);

$orders = $client->orders->list(['limit' => 10]);

Testing and Development

Sandbox Environment

URL: https://api-sandbox.notarial.com
Test Cards: Use provided test card numbers
Test Data: All test data is isolated
No Real Transactions: No actual payments or notarizations

Testing Webhooks

Local Testing:

# Using ngrok for local development
ngrok http 3000

Webhook Testing Tools:
- RequestBin (https://requestbin.com)
- Webhook.site (https://webhook.site)
- ngrok for local testing

Monitoring and Analytics

API Usage Dashboard

Track:

Request volume and patterns
Error rates and types
Response times
Popular endpoints
Integration health

Alerting

Configure alerts for:

High error rates
Unusual usage patterns
Failed webhook deliveries
API key compromises

Getting Help

Resources

API Documentation: https://docs.notarial.com/api
SDK Documentation: https://docs.notarial.com/sdks
Webhook Guide: https://docs.notarial.com/webhooks
Integration Examples: https://github.com/notarial/examples

Support

Developer Support: api-support@notarial.com
Community Forum: https://community.notarial.com
Status Page: https://status.notarial.com
Issue Tracker: https://github.com/notarial/issues

Release Notes

v2.0.0 (Latest)

Added webhook signature verification
Improved rate limiting controls
New SDKs for Go and Ruby
Enhanced error responses

v1.5.0

OAuth 2.0 support added
Bulk operations API
Improved documentation
Performance improvements

v1.0.0

Initial public API release
Core CRUD operations
Basic webhook support
SDKs for JavaScript, Python, PHP

05 API Integrations

Integrations and API Guide

Overview

Integration Categories

1. Email Integrations

2. Messaging Integrations

3. Calendar Integrations

4. CRM Integrations

5. Accounting Integrations

6. Payment Integrations

7. E-Check Integrations

8. API Keys

Table of Contents

Quick Start

Setting Up Your First Integration

Accessing Integrations

Integration Cards

API Management

Accessing API Settings

Generating API Keys

Managing OAuth Clients

API Key Security

API Endpoints

Authentication

Orders

Customers

Invoices

Integration Setup

Authentication Methods

OAuth 2.0 (Recommended)

API Key Authentication

Category-Specific Setup

Email Integrations

Messaging Integrations

Calendar Integrations

CRM Integrations

Accounting Integrations

Google Workspace Integration

Payment Gateway Integration

Stripe Configuration

PayPal Configuration

Dwolla Configuration

DocuSign Integration

Email Service Integration

SendGrid

Mailgun

Webhook Configuration

Creating Webhooks

Supported Events

Order Events

Payment Events

Customer Events

Invoice Events

Webhook Payload Example

Verifying Webhooks

Authentication

1. API Key Authentication (Recommended for Simple Integrations)

2. OAuth 2.0 Client Credentials (Recommended for Server-to-Server)

Step 1: Obtain Client Credentials

Step 2: Request Access Token

Step 3: Use Access Token

3. Session Authentication (For Web Applications)

Creating OAuth Clients

Via Dashboard

Via API

Rate Limiting

Rate Limit Tiers

Rate Limit Headers

Handling Rate Limits

Security Best Practices

API Key Management

Webhook Security

Data Handling

SDKs and Libraries

Official SDKs

JavaScript/Node.js

Python

PHP

Testing and Development

Sandbox Environment