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 tied to your account, allowing you to access your data programmatically.

How to Create an API Key

1. Go to Settings > API Keys in your Salescaling dashboard

2. Click the "Create New API Key"

3. Enter a name for your key (e.g., "Production Integration", "Development")

4. Optionally, set an expiration date for added security

5. Click Create

6. Important: Copy the key immediately - it will only be shown once

7. Store it securely (we recommend using environment variables or a secrets manager)

Using your API Key

• Include the API key in the header x-api-key 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 scopes 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 information about voice agents

• 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

Example Use of Scopes

If you only need to initiate calls via webhook, select only the scope voice-agents:webhook. 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 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 scopes necessary 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 secrets manager

• Rotate keys regularly (recommended every 90 days)

• Immediately delete keys that are unused or compromised

• 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

Manage 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 value of the key cannot be retrieved again

Rate Limiting

Summary

To ensure fair use 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 header Retry-After 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

• Spread 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

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

JavaScript/TypeScript

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

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

Python

import requests

headers = {
    'x-api-key': 'your-api-key-here',
    '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

const axios = require("axios");

const config = {
  headers: {
    "x-api-key": "your-api-key-here",
  },
};

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

• Check our integration examples