API System Identification

Register your integration as a named API System to unlock higher rate limits, per-system usage tracking, and custom rate limit overrides. Systems are identified by a unique System ID sent via the X-System-Id header on every request.

Why Register a System?

Benefit	Without System ID	With System ID
Default rate limit	300 requests/minute	600 requests/minute
Usage tracking	Per-token only	Per-system tracking with `last_used_at`
Custom rate limits	Per-token or per-team	Per-system overrides available
Identification	Anonymous requests	Named system in admin dashboard

Quick Start

Step 1: Register Your System

Use the Partner API to register your integration:

curl -X POST https://api.suresend.ai/api/partner/apiSystems \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My CRM Integration",
    "description": "Syncs contacts from our internal system",
    "contactName": "Jane Developer",
    "contactEmail": "[email protected]"
  }'

Response:

{
  "id": "019cf959-4d26-7e12-afd0-6dcd4ea45b11",
  "name": "My CRM Integration",
  "systemId": "ss_sys_k2RHZfFt4-q9MIlXub1uWrth2FWkDBpF...",
  "displaySystemId": "ss_sys_****...pWE",
  "isActive": true,
  "createdAt": "2026-03-17T01:11:45Z"
}

Important: The full systemId is only returned once at registration. Copy it immediately and store it securely — it cannot be retrieved later.

Step 2: Include System ID in Requests

Add the X-System-Id header to every API request:

curl https://api.suresend.ai/api/partner/people \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-System-Id: ss_sys_k2RHZfFt4-q9MIlXub1uWrth2FWkDBpF..."

That's it — your requests now benefit from 600 requests/minute and per-system tracking.

Registration via Dashboard

You can also register systems through the Sure Send CRM dashboard:

Log in at https://app.suresend.ai
Navigate to Settings > API Systems
Click "Register System"
Fill in your system details and click "Register"
Copy the System ID from the success screen

Code Examples

JavaScript (Node.js)

const axios = require('axios');

const API_TOKEN = process.env.SURESEND_API_TOKEN;
const SYSTEM_ID = process.env.SURESEND_SYSTEM_ID;
const API_URL = 'https://api.suresend.ai/api/partner';

const client = axios.create({
  baseURL: API_URL,
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'X-System-Id': SYSTEM_ID
  }
});

// All requests now include the System ID
const people = await client.get('/people');

Python

import os
import requests

API_TOKEN = os.environ['SURESEND_API_TOKEN']
SYSTEM_ID = os.environ['SURESEND_SYSTEM_ID']
API_URL = 'https://api.suresend.ai/api/partner'

session = requests.Session()
session.headers.update({
    'Authorization': f'Bearer {API_TOKEN}',
    'X-System-Id': SYSTEM_ID
})

# All requests now include the System ID
response = session.get(f'{API_URL}/people')

Ruby

require 'net/http'
require 'json'

API_TOKEN = ENV['SURESEND_API_TOKEN']
SYSTEM_ID = ENV['SURESEND_SYSTEM_ID']
API_URL = 'https://api.suresend.ai/api/partner'

uri = URI("#{API_URL}/people")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{API_TOKEN}"
request['X-System-Id'] = SYSTEM_ID

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

PHP

$apiToken = getenv('SURESEND_API_TOKEN');
$systemId = getenv('SURESEND_SYSTEM_ID');
$apiUrl = 'https://api.suresend.ai/api/partner';

$ch = curl_init("$apiUrl/people");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiToken",
    "X-System-Id: $systemId"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

Managing Your Systems

List Your Systems

curl https://api.suresend.ai/api/partner/apiSystems \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update a System

curl -X PATCH https://api.suresend.ai/api/partner/apiSystems/SYSTEM_UUID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "contactEmail": "[email protected]"
  }'

Deactivate a System

curl -X DELETE https://api.suresend.ai/api/partner/apiSystems/SYSTEM_UUID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Deactivation is a soft delete — the system is marked inactive and its System ID will no longer be recognized in request headers.

Rate Limiting

Default Limits

Scenario	Rate Limit
No System ID	300 requests/minute
Valid System ID	600 requests/minute
Custom rate limit (admin-configured)	Varies

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 60
X-RateLimit-Context: api_system:global

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Window duration in seconds
`X-RateLimit-Context`	Which rate limit rule was applied

When You Exceed the Limit

You'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please retry after 60 seconds.",
  "retry_after": 60
}

Respect the Retry-After header and implement exponential backoff in your integration.

Security Best Practices

Store System IDs securely — treat them like API tokens (environment variables, secrets managers)
Never expose in client-side code — System IDs should only be used in server-to-server requests
One system per integration — register a separate system for each distinct integration or service
Monitor usage — check lastUsedAt to verify your system is being tracked correctly
Deactivate unused systems — remove systems you're no longer using

Limits

Maximum 10 systems per API token
System names must be unique across your account
The full System ID is shown only once at registration

Troubleshooting

System ID Not Recognized

Verify the System ID includes the ss_sys_ prefix
Check that the system hasn't been deactivated
Ensure the header name is exactly X-System-Id (case-sensitive)

Rate Limit Not Increasing

Confirm the System ID is valid and active
Check response headers for X-RateLimit-Limit — it should show 600
If you have custom rate limits configured, those take priority over the default

Registration Fails

Ensure you have at least one API token before registering a system
System names must be unique — check for duplicates
Verify your API token is valid and active