Integration and API Spec

Integration and API Spec

Client Onboarding & Engagement Letters

Central orchestration layer. Manages workflow state, conditional branching, retry logic, and monitoring across all agents. Receives webhook events and dispatches tasks to downstream tools.

// Inbound trigger payload (CRM new-client-won event)
{
  "event": "client.won",
  "client_id": "string",
  "client_name": "string",
  "client_email": "string",
  "service_type": "string",
  "assigned_manager": "string"
}
// Outbound step completion signal
{
  "run_id": "string",
  "step_id": "string",
  "status": "complete | failed",
  "output": { ... }
}

Used by the Engagement Letter Agent to copy a master template document and merge client-specific fields (name, service type, fee, date) before the resulting document URL is handed to PandaDoc.

// Copy template
POST /drive/v3/files/{TEMPLATE_DOC_ID}/copy
Body: { "name": "Engagement Letter - {client_name} - {date}" }

// Merge fields
POST /docs/v1/documents/{new_doc_id}/batchUpdate
Body: { "requests": [
  { "replaceAllText": { "containsText": { "text": "{{client_name}}" }, "replaceText": "{client_name}" } },
  { "replaceAllText": { "containsText": { "text": "{{service_type}}" }, "replaceText": "{service_type}" } }
] }

// Export as PDF
GET /drive/v3/files/{new_doc_id}/export?mimeType=application/pdf

Receives the generated engagement letter PDF, creates a PandaDoc document from it, assigns the client as recipient, and sends for e-signature. A webhook notifies FullSpec Automation when the document is signed.

// Create document from PDF upload
POST /public/v1/documents
Content-Type: multipart/form-data
Fields: file (PDF binary), data (JSON):
{
  "name": "Engagement Letter - {client_name}",
  "recipients": [{ "email": "{client_email}", "first_name": "{first_name}", "last_name": "{last_name}", "role": "client" }],
  "fields": { "signature_1": { "role": "client" } }
}

// Send for signature
POST /public/v1/documents/{document_id}/send
Body: { "message": "Please sign your engagement letter.", "subject": "Your engagement letter is ready" }

// Inbound webhook on completion
{ "event": "document_state_changed", "data": { "id": "string", "status": "document.completed" } }

Used by the Document Collection Agent to send the initial document and ID request email to the client, followed by automated reminder emails on a configured schedule until all items are received or escalated.

// Send document request email
POST /gmail/v1/users/me/messages/send
Body: { "raw": "<base64url RFC2822 message>" }
// Message headers: To: {client_email}, Subject: Action required: documents for your onboarding
// Body includes checklist: proof of identity, proof of address, signed letter confirmation

// Poll for client reply with attachments
GET /gmail/v1/users/me/messages?q=subject:Action+required+from:{client_email}&labelIds=INBOX
// If attachment found, retrieve and pass attachment_id to FullSpec Automation

Used by the Onboarding Setup Agent to create the client contact record, assign the onboarding work item, and set the initial task checklist once all documents and compliance checks are clear.

// Deduplication check
GET /api/v3/contacts?email={client_email}
// If 200 and results array non-empty: skip creation, use existing contact_id

// Create client contact
POST /api/v3/contacts
Body: {
  "type": "Organization",
  "name": "{client_name}",
  "email": "{client_email}",
  "assignedTo": "{manager_user_id}",
  "customFields": { "service_type": "{service_type}" }
}

// Create onboarding work item
POST /api/v3/work
Body: {
  "title": "Onboarding: {client_name}",
  "contactId": "{contact_id}",
  "assignedTo": "{manager_user_id}",
  "dueDate": "{due_date_iso8601}"
}

// ---- Google Workspace (shared OAuth 2.0 application) ----
Credential name : google_workspace_oauth
  GOOGLE_OAUTH_CLIENT_ID       : <Google Cloud Console OAuth client ID>
  GOOGLE_OAUTH_CLIENT_SECRET   : <Google Cloud Console OAuth client secret>
  GOOGLE_OAUTH_REFRESH_TOKEN   : <refresh token obtained via consent flow>
  Scopes                       : https://www.googleapis.com/auth/drive
                                 https://www.googleapis.com/auth/documents
                                 https://www.googleapis.com/auth/gmail.send
                                 https://www.googleapis.com/auth/gmail.readonly

// ---- PandaDoc ----
Credential name : pandadoc_api
  PANDADOC_API_KEY             : <PandaDoc workspace API key>
  PANDADOC_WEBHOOK_SECRET      : <shared secret for HMAC-SHA256 webhook validation>

// ---- Karbon ----
Credential name : karbon_oauth
  KARBON_CLIENT_ID             : <Karbon partner app client ID>
  KARBON_CLIENT_SECRET         : <Karbon partner app client secret>
  KARBON_ACCESS_TOKEN          : <current access token; auto-refreshed by node>
  KARBON_REFRESH_TOKEN         : <refresh token; stored encrypted>

// ---- FullSpec Automation ----
Credential name : fullspec_internal
  FULLSPEC_API_KEY             : <FullSpec workspace API key>
  FULLSPEC_WEBHOOK_SECRET      : <HMAC-SHA256 secret for inbound webhook validation>

// ---- Google Docs template reference (workflow variable, not secret) ----
  ENGAGEMENT_LETTER_TEMPLATE_DOC_ID : <Drive file ID of master template document>

## [MAJOR.MINOR.PATCH] - YYYY-MM-DD
### Changed
- <artefact name>: <description of change>
### Reason
- <business or technical driver for the change>
### Tested by
- <name or role>
### Approved by
- <name or role>