API Introduction

The Salescaling Public API provides programmatic access to manage your calls, meetings, users, contacts, and other data. This guide will help you get started with authentication and understand rate limiting policies.

Authentication

What is an API Key?

API keys are secure tokens that authenticate your requests to the Public API. Each key is unique and linked to your account, allowing you to programmatically access your data.

How to Create an API Key

Go to Settings > API Keys in your Salescaling dashboard
Click the "Create New API Key" button
Enter a name for your key (e.g., "Production Integration", "Development")
Optionally, set an expiration date for enhanced security
Click Create
Important: Copy the key immediately - it will only be shown once
Store it securely (we recommend using environment variables or a secret manager)

Using Your API Key

Include the API key in the x-api-key header for all requests
All Public API endpoints are available at: https://api.salescaling.com/api/v1/
Example request header: x-api-key: your-api-key-here

Scopes (Permissions)

API keys use a scope system to control what actions they can perform. When creating an API key, you must select at least one scope:

Available Scopes

Voice Agents:

voice-agents:webhook - Allows initiating calls via webhook
voice-agents:read - Allows reading voice agent information
voice-agents:write - Allows creating and modifying voice agents

Contacts:

contacts:read - Allows reading contact information
contacts:write - Allows creating and modifying contacts

Companies:

companies:read - Allows reading company information
companies:write - Allows creating and modifying companies

Calls:

calls:read - Allows reading call information
calls:write - Allows creating and modifying calls

Meetings:

meetings:read - Allows reading meeting information
meetings:write - Allows creating and modifying meetings

Opportunities:

opportunities:read - Allows reading opportunity information
opportunities:write - Allows creating and modifying opportunities

Calendar:

calendar:read - Allows reading calendar information
calendar:write - Allows creating and modifying calendar events

Users:

users:read - Allows reading user information

Scope Usage Example

If you only need to initiate calls via webhook, select only the voice-agents:webhook scope. This follows the principle of least privilege, granting only the necessary permissions.

Permissions and Ownership

API keys act on behalf of the user who created them
Scopes limit what actions the API key can perform
Any action performed using an API key will appear as if it were performed by the creating user
For example, if you create a call using an API key, you will appear as the owner of that call
Only create API keys for users with appropriate access levels
Assign only the necessary scopes for each API key

Security Best Practices

Never share your API keys or include them in version control
Store keys in environment variables or a secure secret manager
Rotate keys regularly (every 90 days is recommended)
Immediately delete unused or compromised keys
Assign only the necessary scopes (principle of least privilege)
Create different API keys for different integrations or purposes
Monitor the usage of your API keys regularly
Create separate keys for different environments (development, staging, production)
Use read-only keys when you only need to retrieve data

Managing Your API Keys

View all your keys in Settings > API Keys
Update key names or expiration dates at any time
Delete keys you no longer need
Note: Once created, the full key value cannot be retrieved again

Rate Limiting

Overview

To ensure fair usage and system stability, the API implements rate limiting on all endpoints.

Rate Limits

Three concurrent limits apply to your requests:

Short-term: 20 requests per second
Medium-term: 200 requests per 10 seconds
Long-term: 1,000 requests per minute

How It Works

Limits are tracked per API key
All three limits are active simultaneously
If you exceed any limit, you will receive a 429 error response

Handling Rate Limits

When you receive a 429 (Too Many Requests) response:

Check the Retry-After header to know when to retry
Wait the specified time before making another request
Implement exponential backoff in your retry logic
Example: wait 1s, then 2s, then 4s, etc. between retries

Best Practices

Cache API responses when possible to reduce requests
Use webhooks instead of polling for real-time updates
Batch operations when the API supports it
Distribute requests over time instead of sending bursts
Monitor your usage to stay within limits
If you need higher limits, contact support

Quick Start Examples

cURL

bash

curl -X GET \
  'https://api.salescaling.com/api/v1/users' \
  -H 'x-api-key: tu-api-key-aqui'

JavaScript/TypeScript

typescript

const response = await fetch("https://api.salescaling.com/api/v1/users", {
  headers: {
    "x-api-key": "tu-api-key-aqui",
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);

Python

python

import requests

headers = {
    'x-api-key': 'tu-api-key-aqui',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.salescaling.com/api/v1/users',
    headers=headers
)

data = response.json()
print(data)

Node.js with axios

javascript

const axios = require("axios");

const config = {
  headers: {
    "x-api-key": "tu-api-key-aqui",
  },
};

axios
  .get("https://api.salescaling.com/api/v1/users", config)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error("Error:", error.message);
  });

Next Steps

Explore the available endpoints in the API reference
Learn about Webhooks for real-time notifications
Review our integration examples