Integration and API Spec

Integration and API Spec

Document Management and Filing

The automation uses the Gmail API in push-notification mode (Gmail watch) rather than polling. A watch is registered on the monitored mailbox and Google publishes new message notifications to a configured Pub/Sub topic. The orchestration layer subscribes to that topic and fetches the relevant message and attachment on each notification.

// Trigger input
Pub/Sub push message -> { messageId, historyId, emailAddress }

// Fetched from Gmail API
messages.get(userId, messageId, format='full') -> { payload.headers[], payload.parts[] }

// Output to Classification Agent
{ message_id, from_address, subject, received_at, attachment_filename, attachment_mime_type, attachment_base64 }

DocuSign delivers a webhook (Connect) event to the orchestration layer endpoint whenever an envelope reaches the Completed status. The orchestration layer validates the HMAC signature on every inbound request before processing. The completed document binary is then retrieved via the Envelopes API.

// Inbound webhook payload (Connect event)
POST DOCUSIGN_WEBHOOK_URL
Headers: X-DocuSign-Signature-1: <hmac-sha256>
Body: { envelopeId, status:'completed', completedDateTime, sender.email, recipients.signers[] }

// Document retrieval
GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/combined
-> binary PDF stream

// Output to Classification Agent
{ envelope_id, completed_at, sender_email, recipient_name, document_filename, document_mime_type, document_base64 }

The Filing and Routing Agent uploads the renamed document binary to a pre-determined subfolder path within the organisation's shared Drive. Folder IDs for every document type and party combination are stored in a routing table held in the credential store, not resolved by name at runtime.

// Input from Filing Agent
{ standard_filename, document_type, party_name, document_date, document_base64, mime_type }

// Drive API call
POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Metadata: { name: standard_filename, parents: [resolved_folder_id], mimeType: mime_type }

// Output
{ drive_file_id, drive_web_view_link, folder_id, uploaded_at }

After a document is successfully uploaded to Drive, the Filing and Routing Agent creates a new page in the Notion document register database. The database schema must match the field mapping table in Section 03 exactly. The Notion database ID is stored in the credential store.

// Input from Filing Agent
{ standard_filename, document_type, party_name, document_date, drive_web_view_link, drive_file_id, filed_at }

// Notion API call
POST https://api.notion.com/v1/pages
Headers: Authorization: Bearer NOTION_API_TOKEN, Notion-Version: 2022-06-28
Body: { parent: { database_id: NOTION_DATABASE_ID }, properties: { ... } }

// Output
{ notion_page_id, notion_page_url }

Slack is used for two distinct message types: a confirmation notification sent to the document owner after a successful filing, and an exception alert sent to the Operations Coordinator channel when the Classification Agent cannot confidently classify a document. Both use the chat.postMessage API with the relevant channel IDs stored in the credential store.

// Confirmation message input
{ standard_filename, document_type, party_name, drive_web_view_link, owner_slack_user_id }

// Confirmation Slack API call
POST https://slack.com/api/chat.postMessage
{ channel: owner_slack_user_id, text: 'Filed: {standard_filename}', blocks: [...] }

// Exception alert input
{ original_filename, source: 'gmail'|'docusign', confidence_score, reason_flagged, document_base64 }

// Exception Slack API call
POST https://slack.com/api/files.upload -> attach document
POST https://slack.com/api/chat.postMessage
{ channel: SLACK_CHANNEL_EXCEPTIONS, text: 'Unclassified document requires review: {original_filename}' }

# Google / Gmail
GOOGLE_OAUTH_CLIENT_ID          = '<oauth-client-id>'
GOOGLE_OAUTH_CLIENT_SECRET      = '<oauth-client-secret>'
GOOGLE_OAUTH_REFRESH_TOKEN      = '<offline-refresh-token>'
GMAIL_MONITORED_ADDRESS         = '<monitored-inbox@yourdomain.com>'
GMAIL_PUBSUB_TOPIC              = 'projects/<project-id>/topics/<topic-name>'
GMAIL_LABEL_FILTER              = '["INBOX"]'

# DocuSign
DOCUSIGN_INTEGRATION_KEY_PROD   = '<prod-integration-key>'
DOCUSIGN_INTEGRATION_KEY_SANDBOX= '<sandbox-integration-key>'
DOCUSIGN_USER_ID                = '<api-user-guid>'
DOCUSIGN_ACCOUNT_ID             = '<account-guid>'
DOCUSIGN_BASE_URI               = 'https://na4.docusign.net'
DOCUSIGN_HMAC_SECRET            = '<connect-hmac-secret>'
DOCUSIGN_RSA_PRIVATE_KEY        = '<pem-encoded-private-key>'
DOCUSIGN_WEBHOOK_URL            = 'https://<orchestration-host>/webhooks/docusign'

# Google Drive
GDRIVE_ROOT_SHARED_DRIVE_ID     = '<shared-drive-id>'
GDRIVE_FOLDER_ROUTING_TABLE     = '{"Invoice":{"default":"<folder-id>"},"Contract":{"default":"<folder-id>"},"HR Form":{"default":"<folder-id>"},"Compliance":{"default":"<folder-id>"},"Other":{"default":"<folder-id>"}}'
GDRIVE_UNCLASSIFIED_FOLDER_ID   = '<unclassified-holding-folder-id>'

# Notion
NOTION_API_TOKEN                = 'secret_<internal-integration-token>'
NOTION_DATABASE_ID              = '<document-register-database-id>'

# Slack
SLACK_BOT_TOKEN                 = 'xoxb-<bot-token>'
SLACK_CHANNEL_CONFIRMATIONS     = 'C<channel-id>'
SLACK_CHANNEL_EXCEPTIONS        = 'C<exceptions-channel-id>'
SLACK_OWNER_ROUTING_TABLE       = '{"Invoice":"U<finance-user-id>","Contract":"U<ops-user-id>","HR Form":"U<hr-user-id>","default":"C<channel-id>"}'

# Classification control
CLASSIFICATION_CONFIDENCE_THRESHOLD = '0.82'

# Allowed MIME types (pipe-delimited)
ALLOWED_MIME_TYPES              = 'application/pdf|application/msword|application/vnd.openxmlformats-officedocument.wordprocessingml.document|image/png|image/jpeg'