Integrations API

The Integrations API allows you to programmatically manage OAuth connections, execute integration actions, and handle webhook events.

Authentication

All API requests require authentication using your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.girardai.com/v1/integrations

List Integrations

Get all available integrations and their connection status.

GET /api/v1/integrations

Response

{
  "integrations": [
    {
      "id": "slack",
      "name": "Slack",
      "description": "Team communication and collaboration",
      "category": "communication",
      "connected": true,
      "connectedAt": "2026-02-01T10:00:00Z",
      "features": {
        "triggers": ["message_received", "mention", "reaction_added"],
        "actions": ["send_message", "send_dm", "open_modal"]
      }
    },
    {
      "id": "hubspot",
      "name": "HubSpot",
      "description": "CRM and marketing automation",
      "category": "crm",
      "connected": false,
      "features": {
        "triggers": ["contact_created", "deal_updated"],
        "actions": ["create_contact", "update_contact", "create_deal"]
      }
    }
  ]
}

Connect Integration

Initiate OAuth connection for an integration.

POST /api/v1/integrations/{integrationId}/connect

Parameters

Parameter	Type	Required	Description
redirectUrl	string	No	URL to redirect after OAuth
scopes	array	No	Specific scopes to request

Response

{
  "authUrl": "https://oauth.provider.com/authorize?...",
  "state": "abc123",
  "expiresIn": 600
}

Disconnect Integration

Remove an integration connection.

DELETE /api/v1/integrations/{integrationId}/connection

Response

{
  "success": true,
  "message": "Integration disconnected successfully"
}

Execute Action

Execute an integration action.

POST /api/v1/integrations/{integrationId}/actions/{actionId}

Slack Actions

Send Message

POST /api/v1/integrations/slack/actions/send_message

{
  "channel": "#general",
  "text": "Hello from the API!",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Hello *world*!"
      }
    }
  ]
}

Open Modal

POST /api/v1/integrations/slack/actions/open_modal

{
  "triggerId": "trigger_123",
  "view": {
    "type": "modal",
    "title": {
      "type": "plain_text",
      "text": "My Modal"
    },
    "blocks": [
      {
        "type": "input",
        "element": {
          "type": "plain_text_input"
        },
        "label": {
          "type": "plain_text",
          "text": "Name"
        }
      }
    ]
  }
}

Microsoft Teams Actions

Send Message

POST /api/v1/integrations/microsoft-teams/actions/send_message

{
  "channelId": "channel_123",
  "content": "Hello from Teams!",
  "contentType": "text"
}

HubSpot Actions

Create Contact

POST /api/v1/integrations/hubspot/actions/create_contact

{
  "properties": {
    "email": "john@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "company": "Acme Inc"
  }
}

Update Contact

POST /api/v1/integrations/hubspot/actions/update_contact

{
  "contactId": "contact_123",
  "properties": {
    "lifecyclestage": "customer"
  }
}

Salesforce Actions

Create Lead

POST /api/v1/integrations/salesforce/actions/create_lead

{
  "FirstName": "Jane",
  "LastName": "Smith",
  "Email": "jane@example.com",
  "Company": "TechCorp"
}

Query

POST /api/v1/integrations/salesforce/actions/query

{
  "soql": "SELECT Id, Name, Email FROM Contact WHERE CreatedDate = TODAY"
}

LinkedIn Actions

View Profile

POST /api/v1/integrations/linkedin/actions/view_profile

{
  "accountId": "account_123",
  "profileUrl": "https://linkedin.com/in/johndoe",
  "priority": "normal"
}

Send Connection

POST /api/v1/integrations/linkedin/actions/send_connection

{
  "accountId": "account_123",
  "profileUrl": "https://linkedin.com/in/johndoe",
  "note": "Hi John, I'd love to connect!",
  "delay": 3600
}

List Webhooks

Get all webhooks for an integration.

GET /api/v1/integrations/{integrationId}/webhooks

Response

{
  "webhooks": [
    {
      "id": "webhook_123",
      "event": "message_received",
      "url": "https://yourapp.com/webhooks/slack",
      "active": true,
      "createdAt": "2026-02-01T10:00:00Z"
    }
  ]
}

Create Webhook

Create a webhook subscription.

POST /api/v1/integrations/{integrationId}/webhooks

Request

{
  "event": "contact_created",
  "url": "https://yourapp.com/webhooks/hubspot",
  "secret": "your_webhook_secret"
}

Response

{
  "id": "webhook_456",
  "event": "contact_created",
  "url": "https://yourapp.com/webhooks/hubspot",
  "active": true,
  "secret": "your_webhook_secret",
  "createdAt": "2026-02-08T12:00:00Z"
}

Delete Webhook

Remove a webhook subscription.

DELETE /api/v1/integrations/{integrationId}/webhooks/{webhookId}

Test Connection

Test an integration connection.

POST /api/v1/integrations/{integrationId}/test

Response

{
  "success": true,
  "latency": 245,
  "details": {
    "workspace": "Acme Corp",
    "user": "api-user@acme.com"
  }
}

Error Codes

Code	Description
integration_not_found	Integration does not exist
not_connected	Integration is not connected
auth_expired	OAuth token has expired
rate_limited	Too many requests
action_failed	Action execution failed
invalid_payload	Invalid request payload

Webhook Payload Format

When integration events occur, webhooks receive payloads in this format:

{
  "id": "evt_123",
  "type": "slack.message_received",
  "timestamp": "2026-02-08T12:00:00Z",
  "integration": "slack",
  "data": {
    "channel": "#general",
    "user": "U123456",
    "text": "Hello!",
    "ts": "1707393600.000000"
  },
  "signature": "sha256=..."
}

Verifying Webhook Signatures

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

---

Previous: Webhooks | Next: Error Codes