Integration and API Spec

Integration and API Spec

Client Reporting & Status Updates

Queried by the Status Gathering Agent on the weekly schedule trigger. The integration reads project tasks, sections, and custom fields to build a structured status object per account.

// Input
account_id: string        // internal account identifier
project_gid: string       // resolved from ASANA_PROJECT_GID_MAP
reporting_week: ISO8601   // e.g. 2024-06-03
// Output
{ account_id, project_name, completed_tasks[], blocked_tasks[],
  upcoming_tasks[], last_updated, raw_notes: string }

Used by the Update Drafting Agent to create a new document from a stored template, populate it with the structured status object, and return a shareable document URL for human review.

// Input
account_id: string
account_name: string
report_week: string       // e.g. 'Week of 3 Jun 2024'
completed_summary: string
blockers_summary: string
upcoming_summary: string
// Output
{ document_id: string, document_url: string, review_link: string }

Used by the Send & Log Agent to send the approved client update email from the account manager's address after the human review gate is passed.

// Input
to_email: string          // client contact email
from_address: string      // account manager send-as address
subject: string
body_plain: string
body_html: string         // optional
document_url: string      // linked in email footer
// Output
{ message_id: string, thread_id: string, sent_at: ISO8601 }

Used by the Send & Log Agent to create a CRM engagement (note or email log) against the relevant contact and deal record immediately after the email is sent.

// Input
contact_email: string
account_name: string
report_week: string
document_url: string
sent_at: ISO8601
gmail_message_id: string
am_name: string
// Output
{ note_id: string, contact_id: string, deal_id: string|null,
  logged_at: ISO8601 }

// n8n Credential Store -- required entries

// 1. Asana OAuth2
Credential name : Asana OAuth2
Type            : OAuth2
Client ID       : {{ ASANA_CLIENT_ID }}
Client Secret   : {{ ASANA_CLIENT_SECRET }}
Auth URL        : https://app.asana.com/-/oauth_authorize
Token URL       : https://app.asana.com/-/oauth_token
Scope           : default
PKCE            : enabled

// 2. Google OAuth2 (Docs + Gmail combined)
Credential name : Google OAuth2 -- Reporting
Type            : OAuth2
Client ID       : {{ GOOGLE_CLIENT_ID }}
Client Secret   : {{ GOOGLE_CLIENT_SECRET }}
Auth URL        : https://accounts.google.com/o/oauth2/v2/auth
Token URL       : https://oauth2.googleapis.com/token
Scopes          : https://www.googleapis.com/auth/drive.file
                  https://www.googleapis.com/auth/documents
                  https://www.googleapis.com/auth/gmail.send
                  https://www.googleapis.com/auth/gmail.compose

// 3. HubSpot Private App
Credential name : HubSpot Private App -- Reporting
Type            : Header Auth
Header name     : Authorization
Header value    : Bearer {{ HUBSPOT_PRIVATE_APP_TOKEN }}

// 4. FullSpec Automation internal
Credential name : FullSpec Internal API
Type            : Header Auth
Header name     : x-fs-api-key
Header value    : {{ FULLSPEC_API_KEY }}

// 5. Environment config (stored as n8n env vars)
ASANA_WORKSPACE_GID       = <workspace_gid>
ASANA_PROJECT_GID_MAP     = '{"acc_001":"12345","acc_002":"67890"}'
GDOCS_TEMPLATE_ID         = <template_doc_id>
GDOCS_OUTPUT_FOLDER_ID    = <drive_folder_id>
GMAIL_SEND_AS_ADDRESS     = am@yourcompany.com
HUBSPOT_PORTAL_ID         = <portal_id>
HUBSPOT_DEFAULT_OWNER_ID  = <owner_id>