Developers

Appearance

Quick Start Guide ​

Get up and running with the Sakneen API in minutes.

Step 1: Get Your API Key ​

Contact Sakneen support to obtain your API credentials:

  • Email: [email protected]
  • Provide your company name and intended use case
  • You'll receive your unique API key and assigned domain

Step 2: Test Connection ​

First, test your API key with a health check:

bash
curl --location "https://your-domain/external/apis/v1.0/healthz" \
  --header "api-key: YOUR_API_KEY_HERE"

If successful, you should see a JSON response:

json
{
  "description": "Backend APIs for the Sakneen platform",
  "ok": true,
  "version": "v1.0"
}

Then test creating or upserting a lead:

bash
curl -X POST "https://your-domain/external/apis/v1.0/leads" \
  -H "api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "language: en-us" \
  -d '{
    "recordSystemId": "website-form-test-001",
    "data": {
      "name": "Test Lead",
      "phoneNumber": "+1234567890",
      "project": "Test Project",
      "email": "[email protected]",
      "leadSource": "Website"
    },
    "additionalData": {
      "campaign": "quick-start"
    }
  }'

Note: Replace your-domain with the actual domain provided by Sakneen support.

Step 3: Integrate into Your Application ​

JavaScript/Node.js ​

javascript
const SAKNEEN_API_KEY = "your-api-key-here";
const SAKNEEN_DOMAIN = "your-domain"; // provided by Sakneen support
const BASE_URL = `https://${SAKNEEN_DOMAIN}/external/apis/v1.0`;

async function upsertLead(leadPayload) {
  const response = await fetch(`${BASE_URL}/leads`, {
    method: "POST",
    headers: {
      "api-key": SAKNEEN_API_KEY,
      "Content-Type": "application/json",
      language: "en-us",
    },
    body: JSON.stringify(leadPayload),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return response.json();
}

// Usage
const leadPayload = {
  recordSystemId: "website-form-uuid-001",
  data: {
    name: "John Doe",
    phoneNumber: "+1987654321",
    project: "Downtown Tower",
    email: "[email protected]",
    leadSource: "Website",
  },
  additionalData: {
    landingPage: "/campaigns/summer",
  },
};

upsertLead(leadPayload)
  .then((result) => console.log("Lead saved:", result))
  .catch((error) => console.error("Error:", error));

Python ​

python
import requests
import json

SAKNEEN_API_KEY = 'your-api-key-here'
SAKNEEN_DOMAIN = 'your-domain'  # provided by Sakneen support
BASE_URL = f'https://{SAKNEEN_DOMAIN}/external/apis/v1.0'

def upsert_lead(lead_payload):
    headers = {
        'api-key': SAKNEEN_API_KEY,
        'Content-Type': 'application/json',
        'language': 'en-us'
    }

    response = requests.post(
        f'{BASE_URL}/leads',
        json=lead_payload,
        headers=headers
    )

    response.raise_for_status()
    return response.json()

# Usage
lead_payload = {
    'recordSystemId': 'website-form-uuid-001',
    'data': {
        'name': 'John Doe',
        'phoneNumber': '+1987654321',
        'project': 'Downtown Tower',
        'email': '[email protected]',
        'leadSource': 'Website'
    },
    'additionalData': {
        'landingPage': '/campaigns/summer'
    }
}

try:
    result = upsert_lead(lead_payload)
    print(f'Lead saved: {result}')
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

PHP ​

php
<?php
$sakneenApiKey = 'your-api-key-here';
$sakneenDomain = 'your-domain'; // provided by Sakneen support
$baseUrl = "https://{$sakneenDomain}/external/apis/v1.0";

function upsertLead($leadPayload, $apiKey, $baseUrl) {
    $headers = [
        'api-key: ' . $apiKey,
        'Content-Type: application/json',
        'language: en-us'
    ];

    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => $baseUrl . '/leads',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($leadPayload),
        CURLOPT_HTTPHEADER => $headers,
    ]);

    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);

    if ($httpCode !== 201) {
        throw new Exception("HTTP Error: $httpCode");
    }

    return $response;
}

// Usage
$leadPayload = [
    'recordSystemId' => 'website-form-uuid-001',
    'data' => [
        'name' => 'John Doe',
        'phoneNumber' => '+1987654321',
        'project' => 'Downtown Tower',
        'email' => '[email protected]',
        'leadSource' => 'Website'
    ],
    'additionalData' => [
        'landingPage' => '/campaigns/summer'
    ]
];

try {
    $result = upsertLead($leadPayload, $sakneenApiKey, $baseUrl);
    echo "Lead saved: $result\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Step 4: Handle Responses ​

Success Response (201 Created) ​

json
{
  "ok": true,
  "operation": "create",
  "lead": {
    "_id": "64f1234567890abcdef123456",
    "leadId": 1001,
    "recordSystemId": "website-form-uuid-001",
    "clientId": "64f1234567890abcdef123457",
    "organizationId": "64f1234567890abcdef123458",
    "data": {
      "name": "John Doe",
      "phoneNumber": "+1987654321",
      "project": "Downtown Tower",
      "email": "[email protected]",
      "leadSource": "Website"
    },
    "additionalData": {
      "landingPage": "/campaigns/summer"
    },
    "isActive": true,
    "isFresh": false,
    "createdAt": "2024-08-07T10:30:00.000Z",
    "updatedAt": "2024-08-07T10:30:00.000Z"
  },
  "newLead": {
    "_id": "64f1234567890abcdef123456",
    "leadId": 1001,
    "recordSystemId": "website-form-uuid-001",
    "clientId": "64f1234567890abcdef123457",
    "organizationId": "64f1234567890abcdef123458",
    "data": {
      "name": "John Doe",
      "phoneNumber": "+1987654321",
      "project": "Downtown Tower",
      "email": "[email protected]",
      "leadSource": "Website"
    },
    "additionalData": {
      "landingPage": "/campaigns/summer"
    },
    "isActive": true,
    "isFresh": false,
    "createdAt": "2024-08-07T10:30:00.000Z",
    "updatedAt": "2024-08-07T10:30:00.000Z"
  }
}

Error Response (400 Bad Request) ​

Validation errors can come from DTO checks such as invalid flat email, or from duplicate phoneNumber / phoneNumber2 rules when your organization does not allow conflict leads.

json
{
  "statusCode": 400,
  "message": ["email must be an email"],
  "error": "Bad Request"
}

Step 5: Production Checklist ​

Before going live, ensure you:

  • [ ] Use environment variables for API keys
  • [ ] Implement proper error handling
  • [ ] Add request timeout and retry logic
  • [ ] Use HTTPS in production
  • [ ] Monitor API usage and rate limits
  • [ ] Test with staging environment first

Next Steps ​

Need Help? ​