{"slug":"documentation/02_API_INTEGRATION_DOCS","title":"IntegrateWise API & Integration Developer Documentation","section":"documentation","sectionLabel":"Documentation","status":"unclassified","type":"document","path":"documentation/02_API_INTEGRATION_DOCS.mdx","bytes":17826,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Build Integrations with IntegrateWise\n\n**Version:** 1.0  \n**Last Updated:** January 2026  \n**Base URL:** `https://api.integratewise.com/v1`\n\n---\n\n# Table of Contents\n\n1. [Getting Started](#1-getting-started)\n2. [Authentication](#2-authentication)\n3. [REST API Reference](#3-rest-api-reference)\n4. [Webhooks](#4-webhooks)\n5. [Rate Limits](#5-rate-limits)\n6. [Error Handling](#6-error-handling)\n7. [Sample Payloads](#7-sample-payloads)\n8. [Build Your First Integration](#8-build-your-first-integration)\n9. [SDK Reference](#9-sdk-reference)\n10. [Best Practices](#10-best-practices)\n\n---\n\n# 1. Getting Started\n\n## 1.1 Quick Start (5 Minutes)\n\n```bash\n# 1. Get your API key from Settings → API Keys in the app\n\n# 2. Make your first API call\ncurl -X GET \"https://api.integratewise.com/v1/accounts\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\"\n\n# 3. You'll receive a list of accounts in your organization\n```\n\n## 1.2 Base URLs\n\n| Environment    | Base URL                                   | Purpose   |\n| -------------- | ------------------------------------------ | --------- |\n| **Production** | `https://api.integratewise.com/v1`         | Live data |\n| **Sandbox**    | `https://sandbox.api.integratewise.com/v1` | Testing   |\n\n## 1.3 API Conventions\n\n| Convention     | Description                       |\n| -------------- | --------------------------------- |\n| **Protocol**   | HTTPS only (TLS 1.2+)             |\n| **Format**     | JSON request/response bodies      |\n| **Encoding**   | UTF-8                             |\n| **Dates**      | ISO 8601 (`2026-01-07T10:30:00Z`) |\n| **IDs**        | UUID v4 format                    |\n| **Pagination** | Cursor-based                      |\n| **Versioning** | URL path (`/v1/`)                 |\n\n---\n\n# 2. Authentication\n\n## 2.1 API Key Authentication\n\nAll API requests require authentication via Bearer token.\n\n```http\nAuthorization: Bearer YOUR_API_KEY\n```\n\n### Getting Your API Key\n\n1. Log in to IntegrateWise\n2. Go to **Settings** → **API Keys**\n3. Click **Create API Key**\n4. Give it a descriptive name\n5. Select permission scopes\n6. Copy the key (shown only once)\n\n### API Key Scopes\n\n| Scope               | Permissions                  |\n| ------------------- | ---------------------------- |\n| `read:accounts`     | Read account data            |\n| `write:accounts`    | Create/update accounts       |\n| `read:contacts`     | Read contact data            |\n| `write:contacts`    | Create/update contacts       |\n| `read:deals`        | Read deal data               |\n| `write:deals`       | Create/update deals          |\n| `read:tasks`        | Read task data               |\n| `write:tasks`       | Create/update/complete tasks |\n| `read:health`       | Read health scores           |\n| `read:automations`  | Read automation configs      |\n| `write:automations` | Create/update automations    |\n| `admin:webhooks`    | Manage webhooks              |\n\n## 2.2 OAuth 2.0 (Coming Q2 2026)\n\nFor applications acting on behalf of users:\n\n```\nAuthorization URL: https://auth.integratewise.com/oauth/authorize\nToken URL: https://auth.integratewise.com/oauth/token\n```\n\n## 2.3 SCIM Provisioning (Coming Q3 2026)\n\nEnterprise SSO user provisioning via SCIM 2.0.\n\n---\n\n# 3. REST API Reference\n\n## 3.1 Accounts\n\n### List Accounts\n\n```http\nGET /v1/accounts\n```\n\n**Query Parameters:**\n\n| Parameter    | Type    | Description                                        |\n| ------------ | ------- | -------------------------------------------------- |\n| `page`       | string  | Pagination cursor                                  |\n| `limit`      | integer | Results per page (max 100)                         |\n| `status`     | string  | Filter by status (`active`, `churned`, `prospect`) |\n| `health_min` | integer | Minimum health score (0-100)                       |\n| `health_max` | integer | Maximum health score (0-100)                       |\n| `search`     | string  | Search by name or domain                           |\n| `sort`       | string  | Sort field (`name`, `created_at`, `health_score`)  |\n| `order`      | string  | Sort order (`asc`, `desc`)                         |\n\n**Example Request:**\n\n```bash\ncurl -X GET \"https://api.integratewise.com/v1/accounts?status=active&health_max=40&limit=10\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n      \"name\": \"Acme Corporation\",\n      \"domain\": \"acme.com\",\n      \"industry\": \"Technology\",\n      \"size\": \"mid-market\",\n      \"mrr\": 5000.0,\n      \"arr\": 60000.0,\n      \"currency\": \"USD\",\n      \"status\": \"active\",\n      \"health_score\": 35,\n      \"tags\": [\"enterprise\", \"q1-focus\"],\n      \"created_at\": \"2025-06-15T10:30:00Z\",\n      \"updated_at\": \"2026-01-05T14:22:00Z\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 42,\n    \"limit\": 10,\n    \"has_more\": true,\n    \"next_cursor\": \"eyJpZCI6ImFjY18xMjM0In0=\"\n  }\n}\n```\n\n### Get Account\n\n```http\nGET /v1/accounts/{account_id}\n```\n\n### Create Account\n\n```http\nPOST /v1/accounts\n```\n\n**Request Body:**\n\n```json\n{\n  \"name\": \"New Customer Inc\",\n  \"domain\": \"newcustomer.com\",\n  \"industry\": \"Healthcare\",\n  \"size\": \"smb\",\n  \"status\": \"prospect\",\n  \"mrr\": 0,\n  \"tags\": [\"inbound\", \"demo-scheduled\"],\n  \"custom_fields\": {\n    \"sales_rep\": \"john@company.com\",\n    \"lead_source\": \"webinar\"\n  }\n}\n```\n\n### Update Account\n\n```http\nPATCH /v1/accounts/{account_id}\n```\n\n### Delete Account\n\n```http\nDELETE /v1/accounts/{account_id}\n```\n\n---\n\n## 3.2 Contacts\n\n### List Contacts\n\n```http\nGET /v1/contacts\n```\n\n### Get Contact\n\n```http\nGET /v1/contacts/{contact_id}\n```\n\n### Create Contact\n\n```http\nPOST /v1/contacts\n```\n\n**Request Body:**\n\n```json\n{\n  \"email\": \"jane.doe@acme.com\",\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"title\": \"VP of Engineering\",\n  \"department\": \"Engineering\",\n  \"role_type\": \"decision_maker\",\n  \"account_id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"phone\": \"+1-555-123-4567\"\n}\n```\n\n### Update Contact\n\n```http\nPATCH /v1/contacts/{contact_id}\n```\n\n### Delete Contact\n\n```http\nDELETE /v1/contacts/{contact_id}\n```\n\n---\n\n## 3.3 Deals\n\n### List Deals\n\n```http\nGET /v1/deals\n```\n\n### Create Deal\n\n```http\nPOST /v1/deals\n```\n\n**Request Body:**\n\n```json\n{\n  \"name\": \"Acme Corp - Enterprise Plan\",\n  \"amount\": 50000.0,\n  \"currency\": \"USD\",\n  \"stage\": \"negotiation\",\n  \"probability\": 60,\n  \"expected_close_date\": \"2026-03-31T00:00:00Z\",\n  \"account_id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"deal_type\": \"new\"\n}\n```\n\n---\n\n## 3.4 Tasks\n\n### Create Task\n\n```http\nPOST /v1/tasks\n```\n\n**Request Body:**\n\n```json\n{\n  \"title\": \"Follow up on renewal discussion\",\n  \"description\": \"Schedule call to discuss Q2 renewal terms\",\n  \"status\": \"pending\",\n  \"priority\": \"high\",\n  \"due_date\": \"2026-01-15T17:00:00Z\",\n  \"account_id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"assignee_id\": \"usr_abc456\",\n  \"task_type\": \"call\"\n}\n```\n\n### Complete Task\n\n```http\nPOST /v1/tasks/{task_id}/complete\n```\n\n---\n\n## 3.5 Health Scores\n\n### Get Account Health\n\n```http\nGET /v1/accounts/{account_id}/health\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"account_id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"score\": 72,\n    \"status\": \"healthy\",\n    \"trend\": \"improving\",\n    \"components\": {\n      \"engagement\": 80,\n      \"adoption\": 75,\n      \"support\": 65,\n      \"billing\": 90,\n      \"sentiment\": 70\n    },\n    \"risk_factors\": [\n      {\n        \"factor\": \"support_tickets_high\",\n        \"impact\": \"medium\",\n        \"description\": \"3 open support tickets in last 30 days\"\n      }\n    ],\n    \"calculated_at\": \"2026-01-07T06:00:00Z\"\n  }\n}\n```\n\n### Trigger Health Recalculation\n\n```http\nPOST /v1/accounts/{account_id}/health/calculate\n```\n\n---\n\n## 3.6 Document Generation (Render)\n\n### Generate Document\n\n```http\nPOST /v1/render\n```\n\n**Request Body:**\n\n```json\n{\n  \"template_id\": \"tpl_weekly_status\",\n  \"format\": \"docx\",\n  \"data_query\": {\n    \"accounts\": {\n      \"status\": \"active\",\n      \"health_max\": 50\n    }\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"render_id\": \"rnd_abc123\",\n    \"status\": \"completed\",\n    \"download_url\": \"https://files.integratewise.com/rnd_abc123/report.docx?token=xyz\",\n    \"expires_at\": \"2026-01-08T10:30:00Z\"\n  }\n}\n```\n\n---\n\n# 4. Webhooks\n\n## 4.1 Managing Webhooks\n\n### Create Webhook\n\n```http\nPOST /v1/webhooks\n```\n\n**Request Body:**\n\n```json\n{\n  \"url\": \"https://your-app.com/webhooks/integratewise\",\n  \"events\": [\"account.created\", \"account.updated\", \"deal.won\", \"health.changed\", \"alert.created\"],\n  \"secret\": \"your-webhook-secret-min-32-chars\",\n  \"active\": true\n}\n```\n\n## 4.2 Webhook Events\n\n| Event                  | Description             |\n| ---------------------- | ----------------------- |\n| `account.created`      | New account created     |\n| `account.updated`      | Account fields changed  |\n| `account.deleted`      | Account deleted         |\n| `contact.created`      | New contact created     |\n| `contact.updated`      | Contact fields changed  |\n| `deal.created`         | New deal created        |\n| `deal.stage_changed`   | Deal moved to new stage |\n| `deal.won`             | Deal marked as won      |\n| `deal.lost`            | Deal marked as lost     |\n| `task.created`         | New task created        |\n| `task.completed`       | Task marked complete    |\n| `health.changed`       | Health score changed    |\n| `alert.created`        | New alert triggered     |\n| `automation.triggered` | Automation executed     |\n\n## 4.3 Webhook Payload Format\n\n```json\n{\n  \"id\": \"evt_a1b2c3d4e5f6\",\n  \"type\": \"deal.won\",\n  \"api_version\": \"2026-01-01\",\n  \"created_at\": \"2026-01-07T10:30:00Z\",\n  \"data\": {\n    \"object\": {\n      \"id\": \"deal_xyz\",\n      \"name\": \"Acme Corp\",\n      \"amount\": 50000\n    },\n    \"previous_attributes\": {\n      \"stage\": \"negotiation\"\n    }\n  }\n}\n```\n\n## 4.4 Signature Verification\n\n**Headers:**\n\n```\nX-IntegrateWise-Signature: sha256=abc123...\nX-IntegrateWise-Timestamp: 1704622200\n```\n\n**Node.js Verification:**\n\n```javascript\nconst crypto = require(\"crypto\");\n\nfunction verifyWebhookSignature(payload, signature, timestamp, secret) {\n  const signedPayload = `${timestamp}.${payload}`;\n  const expected = crypto.createHmac(\"sha256\", secret).update(signedPayload).digest(\"hex\");\n\n  return signature === `sha256=${expected}`;\n}\n```\n\n**Python Verification:**\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_webhook_signature(payload, signature, timestamp, secret):\n    signed_payload = f'{timestamp}.{payload}'\n    expected = hmac.new(\n        secret.encode(),\n        signed_payload.encode(),\n        hashlib.sha256\n    ).hexdigest()\n    return signature == f'sha256={expected}'\n```\n\n## 4.5 Retry Policy\n\n| Attempt | Delay                   |\n| ------- | ----------------------- |\n| 1       | Immediate               |\n| 2       | 1 minute                |\n| 3       | 5 minutes               |\n| 4       | 30 minutes              |\n| 5-10    | Exponential (up to 24h) |\n\nAfter 10 failures, webhook is disabled and admin is notified.\n\n---\n\n# 5. Rate Limits\n\n## 5.1 Limits by Tier\n\n| Tier           | Requests/Min | Requests/Hour |\n| -------------- | ------------ | ------------- |\n| **Free**       | 60           | 1,000         |\n| **Pro**        | 300          | 10,000        |\n| **Enterprise** | 1,000        | 100,000       |\n\n## 5.2 Rate Limit Headers\n\n```http\nX-RateLimit-Limit: 300\nX-RateLimit-Remaining: 295\nX-RateLimit-Reset: 1704622260\n```\n\n## 5.3 Handling Rate Limits\n\n```javascript\nasync function apiRequestWithRetry(url, options) {\n  const response = await fetch(url, options);\n\n  if (response.status === 429) {\n    const retryAfter = response.headers.get(\"X-RateLimit-Retry-After\") || 60;\n    await sleep(retryAfter * 1000);\n    return apiRequestWithRetry(url, options);\n  }\n\n  return response;\n}\n```\n\n---\n\n# 6. Error Handling\n\n## 6.1 Error Response Format\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Invalid email format\",\n    \"details\": {\n      \"field\": \"email\",\n      \"constraint\": \"Must be a valid email\"\n    },\n    \"request_id\": \"req_abc123\"\n  }\n}\n```\n\n## 6.2 Error Codes\n\n| Code               | HTTP | Description              |\n| ------------------ | ---- | ------------------------ |\n| `UNAUTHORIZED`     | 401  | Invalid API key          |\n| `FORBIDDEN`        | 403  | Insufficient permissions |\n| `NOT_FOUND`        | 404  | Resource doesn't exist   |\n| `VALIDATION_ERROR` | 400  | Invalid request data     |\n| `RATE_LIMITED`     | 429  | Too many requests        |\n| `INTERNAL_ERROR`   | 500  | Server error             |\n\n---\n\n# 7. Sample Payloads\n\n## 7.1 Account Object\n\n```json\n{\n  \"id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"external_id\": \"hubspot_12345\",\n  \"source\": \"hubspot\",\n  \"name\": \"Acme Corporation\",\n  \"domain\": \"acme.com\",\n  \"industry\": \"Technology\",\n  \"size\": \"mid-market\",\n  \"mrr\": 5000.0,\n  \"arr\": 60000.0,\n  \"currency\": \"USD\",\n  \"status\": \"active\",\n  \"health_score\": 72,\n  \"tags\": [\"enterprise\", \"strategic\"],\n  \"custom_fields\": {\n    \"csm\": \"jane@company.com\",\n    \"region\": \"west\"\n  },\n  \"created_at\": \"2025-06-15T10:30:00Z\",\n  \"updated_at\": \"2026-01-07T14:22:00Z\"\n}\n```\n\n## 7.2 Contact Object\n\n```json\n{\n  \"id\": \"con_b2c3d4e5-f6a7-8901-bcde-f23456789012\",\n  \"email\": \"jane.doe@acme.com\",\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"title\": \"VP of Engineering\",\n  \"role_type\": \"champion\",\n  \"account_id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"engagement_score\": 85,\n  \"last_contacted_at\": \"2026-01-05T10:00:00Z\"\n}\n```\n\n## 7.3 Health Score Object\n\n```json\n{\n  \"account_id\": \"acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"score\": 72,\n  \"status\": \"healthy\",\n  \"trend\": \"improving\",\n  \"components\": {\n    \"engagement\": 80,\n    \"adoption\": 75,\n    \"support\": 65,\n    \"billing\": 90,\n    \"sentiment\": 70\n  },\n  \"risk_factors\": [],\n  \"calculated_at\": \"2026-01-07T06:00:00Z\"\n}\n```\n\n---\n\n# 8. Build Your First Integration\n\n## Tutorial: Slack Alerts for At-Risk Accounts\n\n```javascript\nconst express = require(\"express\");\nconst crypto = require(\"crypto\");\nconst { WebClient } = require(\"@slack/web-api\");\n\nconst app = express();\napp.use(express.json());\n\nconst WEBHOOK_SECRET = process.env.INTEGRATEWISE_WEBHOOK_SECRET;\nconst slack = new WebClient(process.env.SLACK_TOKEN);\n\nfunction verifySignature(req) {\n  const signature = req.headers[\"x-integratewise-signature\"];\n  const timestamp = req.headers[\"x-integratewise-timestamp\"];\n  const payload = JSON.stringify(req.body);\n\n  const signedPayload = `${timestamp}.${payload}`;\n  const expected =\n    \"sha256=\" + crypto.createHmac(\"sha256\", WEBHOOK_SECRET).update(signedPayload).digest(\"hex\");\n\n  return signature === expected;\n}\n\napp.post(\"/webhooks/integratewise\", async (req, res) => {\n  if (!verifySignature(req)) {\n    return res.status(401).send(\"Invalid signature\");\n  }\n\n  res.status(200).send(\"OK\");\n\n  const event = req.body;\n\n  if (event.type === \"health.changed\") {\n    const { object } = event.data;\n\n    if (object.status === \"at_risk\") {\n      await slack.chat.postMessage({\n        channel: \"#customer-alerts\",\n        text: `⚠️ Account at risk: Health score dropped to ${object.score}`,\n      });\n    }\n  }\n});\n\napp.listen(3000);\n```\n\n---\n\n# 9. SDK Reference\n\n## 9.1 JavaScript SDK (Coming Q1 2026)\n\n```bash\nnpm install @integratewise/sdk\n```\n\n```typescript\n\nconst client = new IntegrateWise({\n  apiKey: process.env.INTEGRATEWISE_API_KEY,\n});\n\n// List accounts\nconst accounts = await client.accounts.list({\n  status: \"active\",\n  healthMax: 50,\n});\n\n// Get health score\nconst health = await client.health.get(\"acc_abc123\");\n\n// Webhook handler\nclient.webhooks.on(\"health.changed\", async (event) => {\n  console.log(`Health changed: ${event.data.object.score}`);\n});\n```\n\n## 9.2 Python SDK (Coming Q2 2026)\n\n```bash\npip install integratewise\n```\n\n```python\nfrom integratewise import IntegrateWise\n\nclient = IntegrateWise(api_key=os.environ['INTEGRATEWISE_API_KEY'])\n\n# List accounts\naccounts = client.accounts.list(status='active', health_max=50)\n\n# Get health score\nhealth = client.health.get('acc_abc123')\n```\n\n---\n\n# 10. Best Practices\n\n## 10.1 API Usage\n\n**Paginate large result sets:**\n\n```javascript\nlet cursor = null;\ndo {\n  const response = await client.accounts.list({ limit: 100, page: cursor });\n  accounts.push(...response.data);\n  cursor = response.meta.next_cursor;\n} while (cursor);\n```\n\n**Cache frequently accessed data:**\n\n```javascript\nconst CACHE_TTL = 5 * 60 * 1000;\nconst cache = new Map();\n\nasync function getAccount(id) {\n  const cached = cache.get(id);\n  if (cached && Date.now() - cached.time < CACHE_TTL) {\n    return cached.data;\n  }\n  const account = await client.accounts.get(id);\n  cache.set(id, { data: account, time: Date.now() });\n  return account;\n}\n```\n\n## 10.2 Webhooks\n\n**Respond quickly, process async:**\n\n```javascript\napp.post(\"/webhooks\", (req, res) => {\n  res.status(200).send(\"OK\");\n  processWebhookAsync(req.body);\n});\n```\n\n**Make handlers idempotent:**\n\n```javascript\nasync function processWebhook(event) {\n  const processed = await db.events.findOne({ id: event.id });\n  if (processed) return;\n\n  await handleEvent(event);\n  await db.events.insert({ id: event.id, processedAt: new Date() });\n}\n```\n\n## 10.3 Security\n\n**Store API keys securely:**\n\n```javascript\n// ✅ Environment variables\nconst apiKey = process.env.INTEGRATEWISE_API_KEY;\n\n// ❌ Hardcoded\nconst apiKey = \"iw_live_abc123...\";\n```\n\n**Use minimal scopes:**\n\n```javascript\n// ✅ Only needed scopes\nscopes: [\"read:accounts\", \"read:health\"];\n\n// ❌ All scopes\nscopes: [\"*\"];\n```\n\n---\n\n**IntegrateWise API Documentation**  \n_Version 1.0 — January 2026_\n\nFor questions: api-support@integratewise.com\n"}