Skip to main content
The Clix API enables programmatic control of user management, messaging, campaign execution, and event tracking through server-to-server communication. Built on REST principles, it provides reliable endpoints designed to scale with your engagement needs.

​
What You Can Do

With the Clix API, you can:
  • Manage Users - Create, update, and delete project users; store and update custom user properties for segmentation and personalization
  • Send Messages - Deliver push notifications directly to user devices with custom content
  • Trigger Campaigns - Trigger pre-configured campaigns to specific users or broadcast to your entire user base

​
Base URL

https://api.clix.so
All API requests must use HTTPS (TLS 1.2+) and be directed to the base URL above.

​
Authentication

Every Clix API request requires authentication through two custom headers that identify your project and authorize the request:
HeaderRequiredDescription
X-Clix-Project-IDYesYour project’s unique identifier
X-Clix-API-KeyYesYour API key (public or secret based on operation)

​
API Key Types and Use Cases

Clix distinguishes between two API key types to provide flexibility and security:
Key TypeWhen to UseVisibility
Public API KeyClient-side SDKs in mobile apps, browsers, or public environmentsSafe to expose
Secret API KeyServer-to-server communication, secure backend operationsMust keep confidential

​
Key Selection Guide

  • Public Key: Use for direct SDK integrations where your application frontend communicates with Clix
  • Secret Key: Use for sensitive operations including user management, message sending, and campaign triggering

​
Example Request

curl -X POST https://api.clix.so/api/v1/users \
  -H "X-Clix-Project-ID: your_project_id" \
  -H "X-Clix-API-Key: your_secret_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "project_user_id": "user_123"
    }
  }'

​
Protecting Your API Keys

Secret API keys grant access to your project data and operations. Do not expose them in client-side code, version control repositories, or unencrypted logs. Key compromise may lead to unauthorized data access or operations.
  • Store keys in environment variables or dedicated secrets management platforms
  • Implement key rotation policies in your organization
  • Apply the principle of least privilege—use Public keys in client applications, Secret keys only in trusted backends
  • Regularly audit API key usage and revoke unused keys
  • Enable alerts if unusual API activity is detected

​
Rate Limits

Rate limits are applied to ensure fair usage and maintain service stability. If you exceed your rate limit, the API will return a 429 Too Many Requests response. For detailed information about rate limiting policies and best practices, see Rate Limits.

​
Content Type

The Clix API exclusively uses JSON for request and response bodies. 
Content-Type: application/json

​
Response Codes and Error Handling

Clix API responses follow standard HTTP conventions. The status code indicates the outcome of your request:

​
Success Codes

Status CodeMeaningNotes
200OKRequest processed successfully, response body contains data
201CreatedResource successfully created (e.g., new user)

​
Client Error Codes

Status CodeMeaningWhat to Do
400Bad RequestCheck request parameters, headers, and body format. Refer to endpoint documentation.
401UnauthorizedVerify API key and Project ID are correct and valid
404Not FoundThe resource (user, campaign, etc.) doesn’t exist. Verify the resource ID.
429Too Many RequestsRate limit exceeded. See Rate Limits for retry strategies.

​
Server Error Codes

Status CodeMeaningWhat to Do
500Internal Server ErrorTemporary server issue. Implement exponential backoff and retry.
503Service UnavailableScheduled maintenance or temporary outage. Retry after a delay.

​
Error Response Format

When a request fails, the response body contains an error message: 
{
  "error": "Invalid project user ID format"
}

​
Implementing Reliable Retries

For production integrations, implement exponential backoff to handle transient failures gracefully: 
async function makeRequestWithRetry(url, options, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const response = await fetch(url, options);

      // Don't retry client errors (4xx) - they won't succeed with retry
      if (response.status < 500) {
        return response;
      }

      // On last attempt, throw the error
      if (attempt === maxAttempts - 1) {
        throw new Error(`Server error: ${response.status}`);
      }

      // Calculate exponential backoff: 1s, 2s, 4s, etc.
      const delayMs = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delayMs));
    } catch (error) {
      if (attempt === maxAttempts - 1) throw error;
    }
  }
}

​
OpenAPI Specification

The complete OpenAPI specification for the Clix API is available:

OpenAPI Spec

View the complete OpenAPI specification

​
API Endpoints

​
Users

Store and manage your project’s user profiles. Users can have custom properties used for segmentation, personalization, and targeting.

​
Campaigns

Campaigns are pre-configured message templates set up in your dashboard. Use the API to trigger campaigns to reach your users.
  • Trigger Campaign - Execute a campaign, targeting specific users or broadcast to all users matching campaign filters

​
Messages

Send ad-hoc push notifications outside of campaigns. Useful for transactional or time-sensitive messages.
  • Send Messages - Deliver push notifications directly to specified devices

​
SDK Integration

For easier integration, consider using our official SDKs:

​
Request Timeout

API requests have a maximum execution time of 100 seconds. If your request doesn’t complete within this window, it will be terminated with a timeout error. Ensure your integration handles timeouts gracefully.

​
Integration Guidelines

Build robust integrations with these recommendations:
  • Always use HTTPS - Connections must be encrypted with TLS 1.2 or higher
  • Implement exponential backoff - Automatically retry on 5xx errors with increasing delays (1s, 2s, 4s…)
  • Respect rate limits - Monitor response status and throttle requests to stay within limits
  • Log responses - Track API responses for debugging and monitoring
  • Validate inputs - Check that project user IDs and other identifiers match expected formats
  • Choose keys wisely - Use Public keys for SDKs, Secret keys only for backend services
For rate limiting specifics and strategies, see the Rate Limits guide.

​
Support

Need help? Contact our support team: