Skip to main content

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.
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 support@timelines.ai 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

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:

JWT token generation

Generate a short-lived JWT token with the following payload claims: The token must be signed using the HS256 algorithm with your Partner Secret.
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

Use case examples

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
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
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
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.
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

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.
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.
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