REST Integration APIs

RESTful APIs for building custom integrations, automating workflows, and extending the ThreadSync platform with your own business logic.

Authentication

All API requests require authentication using OAuth 2.0 bearer tokens. Tokens are obtained by exchanging your client credentials for an access token.

Obtaining an Access Token

POST https://api.threadsync.io/v1/auth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

Using the Token

Include the access token in the Authorization header of all API requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

🔐 Token Lifetime

Access tokens expire after 1 hour. Use the refresh token flow for long-running processes, or request a new token before expiration.

Base URL

All API endpoints use the following base URL:

https://api.threadsync.io/v1

The API uses HTTPS exclusively. HTTP requests will be rejected. All responses are JSON-encoded with Content-Type: application/json.

Rate Limits

API requests are rate-limited to ensure fair usage and platform stability:

Plan	Requests/Minute	Requests/Day	Burst
Developer	60	10,000	100
Professional	300	100,000	500
Enterprise	1,000	Unlimited	2,000

Rate limit headers are included in all responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1707523200

Connections API

Manage connections to external systems. Connections store credentials and configuration for each integrated system.

GET /connections

List all connections in your organization.

POST /connections

Create a new connection to an external system.

Request Body

Parameter	Type	Description
`provider` required	string	The system to connect (e.g., "salesforce", "sap", "workday")
`name` required	string	A friendly name for this connection
`config`	object	Provider-specific configuration options
`credentials` required	object	Authentication credentials for the provider

Example: Create Salesforce Connection

POST /connections
{
  "provider": "salesforce",
  "name": "Production Salesforce",
  "config": {
    "sandbox": false,
    "api_version": "v58.0"
  },
  "credentials": {
    "oauth_flow": "jwt_bearer",
    "consumer_key": "3MVG9...",
    "private_key_id": "key_abc123"
  }
}

GET /connections/{id}

Retrieve a specific connection by ID.

PUT /connections/{id}

Update connection configuration or credentials.

DELETE /connections/{id}

Delete a connection. Active syncs using this connection will be stopped.

Syncs API

Configure and manage data synchronization between connected systems.

POST /syncs

Create a new sync configuration.

Request Body

Parameter	Type	Description
`name` required	string	Friendly name for this sync
`source` required	object	Source connection and object configuration
`destination` required	object	Destination connection and object configuration
`schedule`	string	"realtime", "hourly", "daily", or cron expression
`field_mappings`	array	Custom field mapping rules
`filters`	array	Filter conditions for source records

Example: Real-time Contact Sync

POST /syncs
{
  "name": "SF Contacts to Snowflake",
  "source": {
    "connection_id": "conn_sf123",
    "object": "Contact"
  },
  "destination": {
    "connection_id": "conn_snow456",
    "table": "raw.contacts"
  },
  "schedule": "realtime",
  "field_mappings": [
    { "source": "Email", "destination": "email_address" },
    { "source": "FirstName", "destination": "first_name" }
  ]
}

POST /syncs/{id}/run

Trigger an immediate sync run.

GET /syncs/{id}/runs

List sync run history with status and statistics.

Data Operations API

Perform direct data operations for custom integration logic.

POST /data/{connection_id}/query

Execute a read query against a connected system.

POST /data/{connection_id}/write

Write records to a connected system.

Example: Query Salesforce Accounts

POST /data/conn_sf123/query
{
  "object": "Account",
  "fields": ["Id", "Name", "Industry", "AnnualRevenue"],
  "filter": "Industry = 'Technology' AND AnnualRevenue > 1000000",
  "limit": 100
}

Workflows API

Build automated workflows that orchestrate multiple actions across systems.

POST /workflows

Create a new workflow with triggers and actions.

Example: Lead Routing Workflow

POST /workflows
{
  "name": "Enterprise Lead Routing",
  "trigger": {
    "type": "record_created",
    "connection_id": "conn_sf123",
    "object": "Lead",
    "filter": "AnnualRevenue > 5000000"
  },
  "actions": [
    {
      "type": "transform",
      "config": { "enrich_company_data": true }
    },
    {
      "type": "write",
      "connection_id": "conn_hubspot",
      "object": "Contact"
    },
    {
      "type": "notify",
      "channel": "slack",
      "message": "New enterprise lead: {{Lead.Company}}"
    }
  ]
}

Webhooks

Receive real-time notifications when events occur in your integrations.

POST /webhooks

Webhook Events

Event	Description
`sync.completed`	A sync run completed successfully
`sync.failed`	A sync run encountered an error
`connection.health_changed`	Connection health status changed
`workflow.triggered`	A workflow was triggered
`record.created`	A new record was synced
`record.updated`	A record was updated

Webhook Security

All webhook payloads include an HMAC signature in the X-ThreadSync-Signature header. Verify this signature using your webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Triggers API

Configure event-based triggers for automation.

POST /triggers

Create a new trigger configuration.

Trigger Types

Type	Description
`record_created`	Fires when a new record is created
`record_updated`	Fires when a record is modified
`record_deleted`	Fires when a record is deleted
`field_changed`	Fires when a specific field value changes
`schedule`	Fires on a time-based schedule
`api_call`	Fires when called via API

Custom Transforms

Apply custom transformation logic to data as it flows between systems.

POST /transforms

Create a custom transform function.

Transform Functions

Transforms are defined using JavaScript or JSONata expressions:

{
  "name": "Format Phone Numbers",
  "type": "javascript",
  "code": `
    module.exports = (record) => {
      if (record.Phone) {
        record.Phone = record.Phone.replace(/[^0-9]/g, '');
        if (record.Phone.length === 10) {
          record.Phone = '+1' + record.Phone;
        }
      }
      return record;
    };
  `
}

Extensions API

Extend the platform with custom connectors and logic.

POST /extensions

🔧 Extension SDK

Use our Extension SDK to build custom connectors for systems we don't yet support. See the SDK documentation for details.

Error Handling

The API uses standard HTTP status codes and returns detailed error information in a consistent format.

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The 'provider' field is required",
    "details": {
      "field": "provider",
      "constraint": "required"
    },
    "request_id": "req_abc123xyz"
  }
}

Common Error Codes

HTTP Status	Code	Description
400	`INVALID_REQUEST`	Request body or parameters are invalid
401	`UNAUTHORIZED`	Missing or invalid authentication
403	`FORBIDDEN`	Insufficient permissions for this action
404	`NOT_FOUND`	Resource does not exist
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error (contact support)

Ready to Build?

Get your API credentials and start integrating in minutes.

Get API Access

REST Integration APIs

Authentication

Obtaining an Access Token

Using the Token

🔐 Token Lifetime

Base URL

Rate Limits

Connections API

Request Body

Example: Create Salesforce Connection

Syncs API

Request Body

Example: Real-time Contact Sync

Data Operations API

Example: Query Salesforce Accounts

Workflows API

Example: Lead Routing Workflow

Webhooks

Webhook Events

Webhook Security

Triggers API

Trigger Types

Custom Transforms

Transform Functions

Extensions API

🔧 Extension SDK

Error Handling

Error Response Format

Common Error Codes

Ready to Build?

Related Resources

Full API Reference

Developer Tools

Connector Directory

Security & Compliance