Unclassified

IntegrateWise API & Integration Developer Documentation

Build Integrations with IntegrateWise

Version: 1.0
Last Updated: January 2026
Base URL: https://api.integratewise.com/v1

Getting Started
Authentication
REST API Reference
Webhooks
Rate Limits
Error Handling
Sample Payloads
Build Your First Integration
SDK Reference
Best Practices

1. Getting Started

1.1 Quick Start (5 Minutes)

# 1. Get your API key from Settings → API Keys in the app

# 2. Make your first API call
curl -X GET "https://api.integratewise.com/v1/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# 3. You'll receive a list of accounts in your organization

1.2 Base URLs

Environment	Base URL	Purpose
Production	`https://api.integratewise.com/v1`	Live data
Sandbox	`https://sandbox.api.integratewise.com/v1`	Testing

1.3 API Conventions

Convention	Description
Protocol	HTTPS only (TLS 1.2+)
Format	JSON request/response bodies
Encoding	UTF-8
Dates	ISO 8601 (`2026-01-07T10:30:00Z`)
IDs	UUID v4 format
Pagination	Cursor-based
Versioning	URL path (`/v1/`)

2. Authentication

2.1 API Key Authentication

All API requests require authentication via Bearer token.

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Log in to IntegrateWise
Go to Settings → API Keys
Click Create API Key
Give it a descriptive name
Select permission scopes
Copy the key (shown only once)

API Key Scopes

Scope	Permissions
`read:accounts`	Read account data
`write:accounts`	Create/update accounts
`read:contacts`	Read contact data
`write:contacts`	Create/update contacts
`read:deals`	Read deal data
`write:deals`	Create/update deals
`read:tasks`	Read task data
`write:tasks`	Create/update/complete tasks
`read:health`	Read health scores
`read:automations`	Read automation configs
`write:automations`	Create/update automations
`admin:webhooks`	Manage webhooks

2.2 OAuth 2.0 (Coming Q2 2026)

For applications acting on behalf of users:

Authorization URL: https://auth.integratewise.com/oauth/authorize
Token URL: https://auth.integratewise.com/oauth/token

2.3 SCIM Provisioning (Coming Q3 2026)

Enterprise SSO user provisioning via SCIM 2.0.

3. REST API Reference

3.1 Accounts

List Accounts

GET /v1/accounts

Query Parameters:

Parameter	Type	Description
`page`	string	Pagination cursor
`limit`	integer	Results per page (max 100)
`status`	string	Filter by status (`active`, `churned`, `prospect`)
`health_min`	integer	Minimum health score (0-100)
`health_max`	integer	Maximum health score (0-100)
`search`	string	Search by name or domain
`sort`	string	Sort field (`name`, `created_at`, `health_score`)
`order`	string	Sort order (`asc`, `desc`)

Example Request:

curl -X GET "https://api.integratewise.com/v1/accounts?status=active&health_max=40&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Corporation",
      "domain": "acme.com",
      "industry": "Technology",
      "size": "mid-market",
      "mrr": 5000.0,
      "arr": 60000.0,
      "currency": "USD",
      "status": "active",
      "health_score": 35,
      "tags": ["enterprise", "q1-focus"],
      "created_at": "2025-06-15T10:30:00Z",
      "updated_at": "2026-01-05T14:22:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImFjY18xMjM0In0="
  }
}

Get Account

GET /v1/accounts/{account_id}

Create Account

POST /v1/accounts

Request Body:

{
  "name": "New Customer Inc",
  "domain": "newcustomer.com",
  "industry": "Healthcare",
  "size": "smb",
  "status": "prospect",
  "mrr": 0,
  "tags": ["inbound", "demo-scheduled"],
  "custom_fields": {
    "sales_rep": "john@company.com",
    "lead_source": "webinar"
  }
}

Update Account

PATCH /v1/accounts/{account_id}

Delete Account

DELETE /v1/accounts/{account_id}

3.2 Contacts

List Contacts

GET /v1/contacts

Get Contact

GET /v1/contacts/{contact_id}

Create Contact

POST /v1/contacts

Request Body:

{
  "email": "jane.doe@acme.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "title": "VP of Engineering",
  "department": "Engineering",
  "role_type": "decision_maker",
  "account_id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "phone": "+1-555-123-4567"
}

Update Contact

PATCH /v1/contacts/{contact_id}

Delete Contact

DELETE /v1/contacts/{contact_id}

3.3 Deals

List Deals

GET /v1/deals

Create Deal

POST /v1/deals

Request Body:

{
  "name": "Acme Corp - Enterprise Plan",
  "amount": 50000.0,
  "currency": "USD",
  "stage": "negotiation",
  "probability": 60,
  "expected_close_date": "2026-03-31T00:00:00Z",
  "account_id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deal_type": "new"
}

3.4 Tasks

Create Task

POST /v1/tasks

Request Body:

{
  "title": "Follow up on renewal discussion",
  "description": "Schedule call to discuss Q2 renewal terms",
  "status": "pending",
  "priority": "high",
  "due_date": "2026-01-15T17:00:00Z",
  "account_id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assignee_id": "usr_abc456",
  "task_type": "call"
}

Complete Task

POST /v1/tasks/{task_id}/complete

3.5 Health Scores

Get Account Health

GET /v1/accounts/{account_id}/health

Response:

{
  "success": true,
  "data": {
    "account_id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "score": 72,
    "status": "healthy",
    "trend": "improving",
    "components": {
      "engagement": 80,
      "adoption": 75,
      "support": 65,
      "billing": 90,
      "sentiment": 70
    },
    "risk_factors": [
      {
        "factor": "support_tickets_high",
        "impact": "medium",
        "description": "3 open support tickets in last 30 days"
      }
    ],
    "calculated_at": "2026-01-07T06:00:00Z"
  }
}

Trigger Health Recalculation

POST /v1/accounts/{account_id}/health/calculate

3.6 Document Generation (Render)

Generate Document

POST /v1/render

Request Body:

{
  "template_id": "tpl_weekly_status",
  "format": "docx",
  "data_query": {
    "accounts": {
      "status": "active",
      "health_max": 50
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "render_id": "rnd_abc123",
    "status": "completed",
    "download_url": "https://files.integratewise.com/rnd_abc123/report.docx?token=xyz",
    "expires_at": "2026-01-08T10:30:00Z"
  }
}

4. Webhooks

4.1 Managing Webhooks

Create Webhook

POST /v1/webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/integratewise",
  "events": ["account.created", "account.updated", "deal.won", "health.changed", "alert.created"],
  "secret": "your-webhook-secret-min-32-chars",
  "active": true
}

4.2 Webhook Events

Event	Description
`account.created`	New account created
`account.updated`	Account fields changed
`account.deleted`	Account deleted
`contact.created`	New contact created
`contact.updated`	Contact fields changed
`deal.created`	New deal created
`deal.stage_changed`	Deal moved to new stage
`deal.won`	Deal marked as won
`deal.lost`	Deal marked as lost
`task.created`	New task created
`task.completed`	Task marked complete
`health.changed`	Health score changed
`alert.created`	New alert triggered
`automation.triggered`	Automation executed

4.3 Webhook Payload Format

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "deal.won",
  "api_version": "2026-01-01",
  "created_at": "2026-01-07T10:30:00Z",
  "data": {
    "object": {
      "id": "deal_xyz",
      "name": "Acme Corp",
      "amount": 50000
    },
    "previous_attributes": {
      "stage": "negotiation"
    }
  }
}

4.4 Signature Verification

Headers:

X-IntegrateWise-Signature: sha256=abc123...
X-IntegrateWise-Timestamp: 1704622200

Node.js Verification:

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");

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

Python Verification:

import hmac
import hashlib

def verify_webhook_signature(payload, signature, timestamp, secret):
    signed_payload = f'{timestamp}.{payload}'
    expected = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return signature == f'sha256={expected}'

4.5 Retry Policy

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5-10	Exponential (up to 24h)

After 10 failures, webhook is disabled and admin is notified.

5. Rate Limits

5.1 Limits by Tier

Tier	Requests/Min	Requests/Hour
Free	60	1,000
Pro	300	10,000
Enterprise	1,000	100,000

5.2 Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1704622260

5.3 Handling Rate Limits

async function apiRequestWithRetry(url, options) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    const retryAfter = response.headers.get("X-RateLimit-Retry-After") || 60;
    await sleep(retryAfter * 1000);
    return apiRequestWithRetry(url, options);
  }

  return response;
}

6. Error Handling

6.1 Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "constraint": "Must be a valid email"
    },
    "request_id": "req_abc123"
  }
}

6.2 Error Codes

Code	HTTP	Description
`UNAUTHORIZED`	401	Invalid API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource doesn't exist
`VALIDATION_ERROR`	400	Invalid request data
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

7. Sample Payloads

7.1 Account Object

{
  "id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "hubspot_12345",
  "source": "hubspot",
  "name": "Acme Corporation",
  "domain": "acme.com",
  "industry": "Technology",
  "size": "mid-market",
  "mrr": 5000.0,
  "arr": 60000.0,
  "currency": "USD",
  "status": "active",
  "health_score": 72,
  "tags": ["enterprise", "strategic"],
  "custom_fields": {
    "csm": "jane@company.com",
    "region": "west"
  },
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2026-01-07T14:22:00Z"
}

7.2 Contact Object

{
  "id": "con_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "email": "jane.doe@acme.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "title": "VP of Engineering",
  "role_type": "champion",
  "account_id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "engagement_score": 85,
  "last_contacted_at": "2026-01-05T10:00:00Z"
}

7.3 Health Score Object

{
  "account_id": "acc_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "score": 72,
  "status": "healthy",
  "trend": "improving",
  "components": {
    "engagement": 80,
    "adoption": 75,
    "support": 65,
    "billing": 90,
    "sentiment": 70
  },
  "risk_factors": [],
  "calculated_at": "2026-01-07T06:00:00Z"
}

8. Build Your First Integration

Tutorial: Slack Alerts for At-Risk Accounts

const express = require("express");
const crypto = require("crypto");
const { WebClient } = require("@slack/web-api");

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.INTEGRATEWISE_WEBHOOK_SECRET;
const slack = new WebClient(process.env.SLACK_TOKEN);

function verifySignature(req) {
  const signature = req.headers["x-integratewise-signature"];
  const timestamp = req.headers["x-integratewise-timestamp"];
  const payload = JSON.stringify(req.body);

  const signedPayload = `${timestamp}.${payload}`;
  const expected =
    "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET).update(signedPayload).digest("hex");

  return signature === expected;
}

app.post("/webhooks/integratewise", async (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).send("Invalid signature");
  }

  res.status(200).send("OK");

  const event = req.body;

  if (event.type === "health.changed") {
    const { object } = event.data;

    if (object.status === "at_risk") {
      await slack.chat.postMessage({
        channel: "#customer-alerts",
        text: `⚠️ Account at risk: Health score dropped to ${object.score}`,
      });
    }
  }
});

app.listen(3000);

9. SDK Reference

9.1 JavaScript SDK (Coming Q1 2026)

npm install @integratewise/sdk


const client = new IntegrateWise({
  apiKey: process.env.INTEGRATEWISE_API_KEY,
});

// List accounts
const accounts = await client.accounts.list({
  status: "active",
  healthMax: 50,
});

// Get health score
const health = await client.health.get("acc_abc123");

// Webhook handler
client.webhooks.on("health.changed", async (event) => {
  console.log(`Health changed: ${event.data.object.score}`);
});

9.2 Python SDK (Coming Q2 2026)

pip install integratewise

from integratewise import IntegrateWise

client = IntegrateWise(api_key=os.environ['INTEGRATEWISE_API_KEY'])

# List accounts
accounts = client.accounts.list(status='active', health_max=50)

# Get health score
health = client.health.get('acc_abc123')

10. Best Practices

10.1 API Usage

Paginate large result sets:

let cursor = null;
do {
  const response = await client.accounts.list({ limit: 100, page: cursor });
  accounts.push(...response.data);
  cursor = response.meta.next_cursor;
} while (cursor);

Cache frequently accessed data:

const CACHE_TTL = 5 * 60 * 1000;
const cache = new Map();

async function getAccount(id) {
  const cached = cache.get(id);
  if (cached && Date.now() - cached.time < CACHE_TTL) {
    return cached.data;
  }
  const account = await client.accounts.get(id);
  cache.set(id, { data: account, time: Date.now() });
  return account;
}

10.2 Webhooks

Respond quickly, process async:

app.post("/webhooks", (req, res) => {
  res.status(200).send("OK");
  processWebhookAsync(req.body);
});

Make handlers idempotent:

async function processWebhook(event) {
  const processed = await db.events.findOne({ id: event.id });
  if (processed) return;

  await handleEvent(event);
  await db.events.insert({ id: event.id, processedAt: new Date() });
}

10.3 Security

Store API keys securely:

// ✅ Environment variables
const apiKey = process.env.INTEGRATEWISE_API_KEY;

// ❌ Hardcoded
const apiKey = "iw_live_abc123...";

Use minimal scopes:

// ✅ Only needed scopes
scopes: ["read:accounts", "read:health"];

// ❌ All scopes
scopes: ["*"];

IntegrateWise API Documentation
Version 1.0 — January 2026

For questions: api-support@integratewise.com

Build Integrations with IntegrateWise

Table of Contents

1. Getting Started

1.1 Quick Start (5 Minutes)

1.2 Base URLs

1.3 API Conventions

2. Authentication

2.1 API Key Authentication

Getting Your API Key

API Key Scopes

2.2 OAuth 2.0 (Coming Q2 2026)

2.3 SCIM Provisioning (Coming Q3 2026)

3. REST API Reference

3.1 Accounts

List Accounts

Get Account

Create Account

Update Account

Delete Account

3.2 Contacts

List Contacts

Get Contact

Create Contact

Update Contact

Delete Contact

3.3 Deals

List Deals

Create Deal

3.4 Tasks

Create Task

Complete Task

3.5 Health Scores

Get Account Health

Trigger Health Recalculation

3.6 Document Generation (Render)

Generate Document

4. Webhooks

4.1 Managing Webhooks

Create Webhook

4.2 Webhook Events

4.3 Webhook Payload Format

4.4 Signature Verification

4.5 Retry Policy

5. Rate Limits

5.1 Limits by Tier

5.2 Rate Limit Headers

5.3 Handling Rate Limits

6. Error Handling

6.1 Error Response Format

6.2 Error Codes

7. Sample Payloads

7.1 Account Object

7.2 Contact Object

7.3 Health Score Object

8. Build Your First Integration

Tutorial: Slack Alerts for At-Risk Accounts

9. SDK Reference

9.1 JavaScript SDK (Coming Q1 2026)

9.2 Python SDK (Coming Q2 2026)

10. Best Practices

10.1 API Usage

10.2 Webhooks

10.3 Security