Skip to main content
POST
/
api
/
clients
Create Client
curl --request POST \
  --url https://api.example.com/api/clients \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "domain": "<string>",
  "contactName": "<string>",
  "contactEmail": "<string>"
}
'
{
  "id": "<string>",
  "name": "<string>",
  "domain": "<string>",
  "contactName": "<string>",
  "contactEmail": "<string>",
  "userId": "<string>",
  "googleSearchConsoleConnected": true,
  "googleAnalyticsConnected": true,
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "error": "<string>",
  "requiresVerification": true,
  "upgradeRequired": true,
  "currentCount": 123,
  "limit": 123,
  "details": [
    {}
  ]
}

​
Authentication

Requires authenticated user session. User must meet one of the following criteria:
  • Active PayPal subscription
  • Paid trial signup flow
  • Free signup with verified email

​
Request Body

​
name
string
required
Client name (minimum 2 characters)
​
domain
string
required
Client website domain (must be a valid URL)
​
contactName
string
Primary contact person’s name
​
contactEmail
string
Primary contact email address (must be valid email format)

​
Response

​
id
string
Unique client identifier (CUID format)
​
name
string
Client name
​
domain
string
Client website URL
​
contactName
string
Contact person name
​
contactEmail
string
Contact email address
​
userId
string
ID of the user who owns this client
​
googleSearchConsoleConnected
boolean
Whether Google Search Console is connected (default: false)
​
googleAnalyticsConnected
boolean
Whether Google Analytics is connected (default: false)
​
createdAt
string
ISO 8601 timestamp when client was created
​
updatedAt
string
ISO 8601 timestamp when client was last updated

​
Validation Rules

  • name: Minimum 2 characters
  • domain: Must be a valid URL format
  • contactEmail: Must be valid email format (if provided)

​
Plan Limits

Users are subject to client creation limits based on their subscription plan:
  • FREE: Limited number of clients
  • PAID PLANS: Higher or unlimited clients based on tier
If limit is reached, the API returns a 403 error with upgrade information.

​
Error Responses

​
error
string
Error message describing what went wrong
​
requiresVerification
boolean
Indicates if email verification is required (403 errors)
​
upgradeRequired
boolean
Indicates if plan upgrade is needed (403 errors)
​
currentCount
number
Current number of clients (when limit reached)
​
limit
number
Maximum allowed clients for current plan
​
details
array
Validation error details (400 errors)

​
Example Request

cURL
curl -X POST https://your-domain.com/api/clients \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=..." \
  -d '{
    "name": "Acme Corporation",
    "domain": "https://acme.com",
    "contactName": "John Doe",
    "contactEmail": "[email protected]"
  }'
JavaScript
const response = await fetch('/api/clients', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Corporation',
    domain: 'https://acme.com',
    contactName: 'John Doe',
    contactEmail: '[email protected]'
  })
});

const client = await response.json();

​
Example Response

201 Success
{
  "id": "clx1a2b3c4d5e6f7g8h9i0j1k",
  "name": "Acme Corporation",
  "domain": "https://acme.com",
  "contactName": "John Doe",
  "contactEmail": "[email protected]",
  "userId": "clx0a1b2c3d4e5f6g7h8i9j0k",
  "googleSearchConsoleConnected": false,
  "googleAnalyticsConnected": false,
  "searchConsolePropertyUrl": null,
  "googleAnalyticsPropertyId": null,
  "lastReportGenerated": null,
  "totalReportsGenerated": 0,
  "createdAt": "2024-03-15T10:30:00.000Z",
  "updatedAt": "2024-03-15T10:30:00.000Z"
}
400 Validation Error
{
  "error": "Validation error",
  "details": [
    {
      "code": "too_small",
      "minimum": 2,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "message": "Name must be at least 2 characters",
      "path": ["name"]
    }
  ]
}
403 Email Verification Required
{
  "error": "Please verify your email before adding clients",
  "requiresVerification": true,
  "verificationRequired": true
}
403 Plan Limit Reached
{
  "error": "You have reached your plan limit of 3 clients",
  "currentCount": 3,
  "limit": 3,
  "upgradeRequired": true
}
401 Unauthorized
{
  "error": "Unauthorized"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us