Partner API Overview

Programmatically manage TimelinesAI workspaces, users, and WhatsApp connections for your platform

Partner API

The TimelinesAI Partner API enables B2B partners to programmatically provision and manage workspaces, users, and WhatsApp account connections. This server-to-server API allows partners to integrate TimelinesAI capabilities directly into their own platforms without requiring end-users to interact with the TimelinesAI UI.

The Partner API uses JWT authentication, separate from the Public API’s bearer token. See Getting started below to set up your partner credentials.

Billing

Understanding the billing model is essential before provisioning workspaces and connecting WhatsApp accounts.

Partners are invoiced monthly in arrears based on connected WhatsApp accounts, not provisioned seats or created users. A WhatsApp account counts toward billing from the moment it is connected until it is explicitly disconnected.

Concept	How it works
Billing unit	Each connected WhatsApp account (not seats or users)
Billing cycle	Monthly in arrears
Seats	Control the maximum number of users/WhatsApp accounts in a workspace (1–99). Seats are a capacity limit, not a billing unit.
Trials & offboarding	If a customer trial does not convert, actively disconnect their WhatsApp account using POST /workspaces/{id}/users/{user_id}/whatsapp/disconnect to stop billing. Simply deleting or ignoring the workspace is not enough — the connected account will continue to be billed.
Seat downgrades	When you reduce seats_purchased below current utilization, the platform may automatically suspend users and their associated WhatsApp accounts to comply with the new limit.
Quota monitoring	Subscribe to workspace:seats_full Partner API Webhooks to get alerted when all seats are utilized, so you can proactively manage capacity.

Always track the mapping between your customers and their workspace_id / user_id / WhatsApp account connections. This allows you to promptly disconnect accounts when a customer churns, preventing unnecessary charges.

Getting started

To begin using the Partner API, you need to have your partner records created in the TimelinesAI system. This is a one-time setup process.

1. Contact TimelinesAI

   Reach out to TimelinesAI at [e-mail] to request partner access. The team will set up your partner records in the system.

2. Receive your credentials

   Once your partner account is provisioned, you will receive two credentials:

   • Partner ID — your unique partner identifier (e.g., your-company-name)
   • Partner Secret — a secure key used to sign JWT tokens (keep this confidential)
3. Generate a JWT token

   Use your credentials to generate a short-lived JWT token for authenticating API requests. See the Authentication section below for code examples.

4. Start making API calls

   Include the generated JWT token in the Authorization header and your Partner ID in the X-TL-Partner-Id header with every request.

Base URL

https://app.timelines.ai/partner/api/v1

Authentication

The Partner API uses JWT (JSON Web Token) bearer authentication. Each request must include a valid JWT token signed with your Partner Secret using the HS256 algorithm.

Required headers

Include the following headers in all API requests:

Header	Value
Authorization	Bearer <jwt_token>
X-TL-Partner-Id	Your partner ID
Content-Type	application/json

JWT token generation

Generate a short-lived JWT token with the following payload claims:

Claim	Type	Description
partner_id	string	Your partner identifier
nbf	number	Not before — set to 3 minutes in the past (Unix timestamp)
exp	number	Expiration — set to 3 minutes in the future (Unix timestamp)

The token must be signed using the HS256 algorithm with your Partner Secret.

JavaScript

const jwt = require('jsonwebtoken');

// Configuration
const PARTNER_ID = 'your-partner-id';
const PARTNER_SECRET = 'your-partner-secret';
const BASE_URL = 'https://app.timelines.ai/partner/api/v1';

// Generate JWT token
function generateToken() {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign({
    partner_id: PARTNER_ID,
    nbf: now - 180,    // Valid from 3 min ago
    exp: now + 180     // Expires in 3 min
  }, PARTNER_SECRET);
}

// Make authenticated request
async function apiRequest(method, endpoint, body = null) {
  const token = generateToken();
  const options = {
    method: method,
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-TL-Partner-Id': PARTNER_ID,
      'Content-Type': 'application/json'
    }
  };
  if (body) options.body = JSON.stringify(body);

  const response = await fetch(`${BASE_URL}${endpoint}`, options);
  return response.json();
}

JWT tokens are short-lived (6-minute window). Generate a fresh token for each API request rather than caching tokens.

Capabilities

Workspaces

Create and manage customer workspaces with configurable seat allocations. Update display names and scale seats up or down.

User Management

Create placeholder users in batch — each user consumes one seat and can have a WhatsApp account connected.

QR Code Onboarding

Generate QR code links for users to connect their WhatsApp accounts by scanning. Supports embedded (iframe) and standalone modes.

WhatsApp Accounts

Forcibly disconnect WhatsApp accounts from users when needed.

API Token Management

Retrieve and rotate Public API tokens for any managed workspace. Tokens don’t expire unless explicitly rotated.

Available endpoints

Group	Endpoint	Description
Workspaces	POST /workspaces	Create a new partner-managed workspace with specified seats
	GET /workspaces/{workspace_id}	Get workspace details including quotas, users, and WhatsApp accounts
	PATCH /workspaces/{workspace_id}	Update workspace display name and/or seat count
Users	POST /workspaces/{workspace_id}/users	Create placeholder users in batch (each consumes one seat)
QR Codes	POST /workspaces/{workspace_id}/users/{user_id}/qr	Generate a QR code link for WhatsApp connection
WhatsApp	POST /workspaces/{workspace_id}/users/{user_id}/whatsapp/disconnect	Disconnect a WhatsApp account from a user
API Tokens	GET /workspaces/{workspace_id}/api-token	Retrieve the Public API token (creates one if needed)
	POST /workspaces/{workspace_id}/api-token	Rotate the Public API token (invalidates the old one immediately)

Use case examples

White-label WhatsApp platform

Embed WhatsApp messaging into your own SaaS product without exposing TimelinesAI to your end users.

1. Use POST /workspaces to create a workspace when a customer signs up
2. Create users with POST /workspaces/{id}/users (one per WhatsApp number they need)
3. Generate QR codes with POST /workspaces/{id}/users/{user_id}/qr — embed in your UI using display_mode=embedding
4. Retrieve their Public API token with GET /workspaces/{id}/api-token
5. Use the Public API token in your backend to send/receive messages on their behalf

Managed service provider

Offer WhatsApp as a service to multiple clients, managing everything from a single integration.

1. Provision workspaces per client with POST /workspaces
2. Configure seat allocations with PATCH /workspaces/{id}
3. Onboard client WhatsApp numbers via QR codes
4. Monitor workspace health using Partner API Webhooks (quota alerts, account connectivity)
5. Rotate API tokens periodically for security with POST /workspaces/{id}/api-token

Automated customer onboarding

Streamline the setup process so new customers can start using WhatsApp within minutes.

1. Create workspace automatically when customer completes your sign-up flow
2. Create users in batch for the number of WhatsApp accounts they need
3. Present QR codes in your UI (iframe with display_mode=embedding to avoid session logout)
4. Listen for whatsapp_account:connected webhook to detect successful connection
5. Retrieve the Public API token and begin message syncing automatically

Security & compliance management

Maintain control over API access across all managed workspaces.

1. Rotate Public API tokens periodically with POST /workspaces/{id}/api-token
2. Subscribe to api-token:rotated webhook to track all token changes
3. Disconnect compromised WhatsApp accounts with the disconnect endpoint
4. Monitor quota webhooks for billing compliance and to prevent service interruption

Typical integration flow

1. Create a workspace

   POST /workspaces with display_name and seats_purchased — save the returned workspace_id for all subsequent operations

2. Create users

   POST /workspaces/{id}/users with the count of users needed — each user consumes one seat

3. Generate QR codes

   POST /workspaces/{id}/users/{user_id}/qr for each user — present the QR link in your UI for WhatsApp scanning

4. Retrieve API token

   GET /workspaces/{id}/api-token — use this token with the Public API to send/receive messages

QR code embedding

By default, the QR link opens a standalone page. To embed it within your application (e.g., in an iframe), append display_mode=embedding to the QR link URL.

Mode	Behavior
Embedded (display_mode=embedding)	Does not log the user out of your application. Optimized for iframe usage.
Standalone (default)	Opens a full page — will trigger a logout from the current session.

Generating a new QR code disconnects any existing WhatsApp account for that user. Cache and reuse QR links while a connection attempt is active — only request a new one after the previous attempt completes or expires.

Important notes

API tokens

Public API tokens obtained via GET /api-token do not expire automatically. A token remains valid indefinitely unless explicitly rotated via POST /api-token. The old token is invalidated immediately upon rotation.

Workspace IDs

Always store workspace_id and user_id mappings in your system. There is currently no list-workspaces endpoint — losing a workspace ID requires a support ticket.

WhatsApp account health

Warm up new WhatsApp accounts before automation — exchange messages with 3–5 contacts first. Poll delivery statuses before running automation sequences. See WhatsApp mass messaging best practices for details.

Next steps

Partner API Webhooks

Get real-time notifications for workspace events

Public API

Learn about the Public API for message management