Skip to content
SellerCockpit

API Overview

The SellerCockpit API provides programmatic access to your CRM data, enabling you to build custom integrations with automation platforms like n8n, Zapier, and Make.com, or create your own applications.

API Basics

Base URL

All API requests are made to your Supabase project URL:

https://{project-ref}.supabase.co/functions/v1/api-v1-{resource}

Replace {project-ref} with your actual Supabase project reference and {resource} with the specific endpoint (e.g., contacts, organizations, deals).

Example:

https://abcdefghijklmno.supabase.co/functions/v1/api-v1-contacts

Versioning

The API is currently at version 1 (v1). All endpoints include the version in the URL path: /api-v1-{resource}.

We maintain backward compatibility within major versions. If breaking changes are required, we’ll release a new major version (e.g., v2) and provide migration guidance.

Request Format

  • Protocol: HTTPS only
  • Content-Type: application/json for request bodies
  • Accept: application/json for responses
  • Character Encoding: UTF-8

Response Format

All API responses return JSON with a consistent structure:

Success Response (Single Resource)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp",
    "email": "contact@acme.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Success Response (Multiple Resources)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Beta Inc"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "cursor": "eyJpZCI6ImFiYy...",
    "next_cursor": "eyJpZCI6ImRlZi...",
    "has_more": true
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      }
    ]
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

Status CodeMeaning
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request format or parameters
401Unauthorized - Missing or invalid API key
403Forbidden - API key lacks required permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists or conflict detected
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our end
503Service Unavailable - Temporary service disruption

Error Codes

In addition to HTTP status codes, error responses include a specific error code:

Authentication Errors

  • UNAUTHORIZED - No API key provided
  • INVALID_API_KEY - API key format is invalid or key doesn’t exist
  • API_KEY_REVOKED - API key has been revoked
  • API_KEY_EXPIRED - API key has expired
  • INSUFFICIENT_PERMISSIONS - API key lacks required scope

Rate Limiting Errors

  • RATE_LIMIT_EXCEEDED - Per-minute rate limit exceeded
  • DAILY_LIMIT_EXCEEDED - Daily request limit exceeded

Validation Errors

  • VALIDATION_ERROR - Request validation failed
  • INVALID_REQUEST - Malformed request
  • MISSING_REQUIRED_FIELD - Required field is missing

Resource Errors

  • NOT_FOUND - Resource not found
  • ALREADY_EXISTS - Resource with identifier already exists
  • CONFLICT - Operation conflicts with current state

Server Errors

  • INTERNAL_ERROR - Unexpected server error
  • SERVICE_UNAVAILABLE - Service temporarily unavailable

Plan Limit Errors

  • FEATURE_NOT_ENABLED - Feature not available on current plan
  • PLAN_LIMIT_EXCEEDED - Plan resource limit exceeded

CORS Support

The API supports Cross-Origin Resource Sharing (CORS) for browser-based requests:

  • Access-Control-Allow-Origin: * (all origins)
  • Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
  • Access-Control-Allow-Headers: authorization, x-client-info, apikey, content-type
  • Access-Control-Max-Age: 86400 (24 hours)

Rate Limiting

All API requests are subject to rate limiting to ensure fair usage. See the Rate Limits page for details on limits and handling rate limit errors.

Authentication

API authentication uses API keys with scope-based permissions. See the Authentication page for details on creating and using API keys.

Pagination

List endpoints support both cursor-based and offset-based pagination. See the Pagination page for details on paginating through large result sets.

Getting Help

Next Steps