Sketchief|
Guides
Back to Home

How to Use the API

Last updated February 19, 2026

The Sketchief API allows you to integrate opener generation directly into your applications, workflows, and tools. This guide will walk you through setting up API access and making your first API calls.

Note: API access is available on Business and Enterprise plans only.

What You Can Do with the API

The API enables you to:

  • Generate personalised openers programmatically
  • Automate opener creation for incoming leads
  • Integrate Sketchief into your existing CRM or sales tools
  • Build custom workflows and automations
  • Scale your outreach without manual campaign creation

Prerequisites

Before you start, make sure you have:

  • A Sketchief account on a Business or Enterprise plan
  • Basic knowledge of making HTTP requests
  • A tool for testing API calls (Postman, Insomnia, curl, or your programming language of choice)

Step 1: Access the API Section

  1. Log into your Sketchief dashboard
  2. In the left sidebar, find the AUTOMATION section
  3. Click "API Access"

You'll see the API Access page with two tabs:

  • API Keys (for managing your keys)
  • Documentation (for technical reference)

Step 2: Create an API Key

The API Keys tab should be selected by default. You'll see:

  • Section title: "Your API Keys"
  • Subtitle: "Manage your API keys for programmatic access"

Generate a New Key

  1. Click the blue "Create API Key" button in the top right
  2. Give your API key a descriptive name (e.g., "Production App", "Testing", "CRM Integration")
  3. Click "Create"
  4. Important: Copy your API key immediately and store it securely
  • API keys are shown only once during creation
  • You won't be able to see the full key again

Understanding Your API Keys

Each API key displays:

  • Key name - The name you gave it
  • Masked key - Format: sk_xxxxxx••••••••••••••••
  • Created date - When the key was generated
  • Last used - When it was last used (or "Never")
  • Request count - Total number of API calls made with this key
  • Delete button - Red trash icon to revoke the key

Managing Multiple Keys

You can create multiple API keys for different purposes:

  • One for production
  • One for testing/development
  • One for each integration or tool
  • This helps you track usage and revoke access without affecting other integrations

Understanding Opener Versions

Sketchief offers two versions of openers:

V1 Openers (Default)

  • Traditional personalized openers
  • Returns results immediately in the API response
  • Simple one-step process
  • Perfect for quick integrations

V2 Openers (Enhanced)

  • Enhanced with your company context
  • More relevant personalization based on your website
  • Requires userWebsite parameter
  • Uses async workflow: generate → wait 30-40 seconds → retrieve
  • Best for highly personalized outreach

Default behavior: If you don't specify opener_version, the API uses V1.

API Reference

Base URL

All API requests should be sent to:

https://sketchief.com/api

Authentication

Every API request must include your API key in the request header:

X-API-Key: your_api_key_here

Replace your_api_key_here with your actual API key (the full unmasked version you copied when creating it).

Using V1 Openers (Immediate Response)

V1 openers return immediately with the generated opener in the response. This is the simplest way to use the API.

Endpoint

POST /generate-opener

Sales Navigator Example

curl -X POST \
  https://sketchief.com/api/generate-opener \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_type": "salesnav",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "companyName": "Acme Inc",
    "regularCompanyUrl": "https://acme.com",
    "industry": "Technology",
    "companyLocation": "San Francisco, CA",
    "title": "VP of Engineering",
    "summary": "Experienced technology leader...",
    "titleDescription": "Leads engineering team..."
  }'

Normal Leads Example

curl -X POST \
  https://sketchief.com/api/generate-opener \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_type": "normal",
    "fullName": "Jane Smith",
    "firstName": "Jane",
    "lastName": "Smith",
    "companyName": "Tech Corp",
    "personalLinkedin": "https://linkedin.com/in/janesmith",
    "website": "https://techcorp.com"
  }'

Note: For normal leads, either website or email must be provided.

V1 Response

When successful, you'll receive an immediate response:

{
  "success": true,
  "status": "completed",
  "opener_id": "uuid",
  "opener_version": 1,
  "fullName": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "companyName": "Tech Corp",
  "opener": "Hi Jane, I came across...",
  "subjectLine": "Connecting about Tech Corp",
  "email": "jane@techcorp.com"
}

Using V2 Openers (Enhanced with Async Workflow)

V2 openers provide enhanced personalization using your company context. They require a three-step async workflow.

Workflow Overview

Step 1: Generate opener (returns immediately with opener_id)

Step 2: Wait 30-40 seconds

Step 3: Fetch results with opener_id

Step 1: Generate Opener

Add opener_version: "v2" and your userWebsite to the request:

Sales Navigator Example:

curl -X POST \
  https://sketchief.com/api/generate-opener \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "opener_version": "v2",
    "workflow_type": "salesnav",
    "userWebsite": "https://yourcompany.com",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "companyName": "Acme Inc",
    "regularCompanyUrl": "https://acme.com",
    "industry": "Technology",
    "companyLocation": "San Francisco, CA",
    "title": "VP of Engineering",
    "summary": "Experienced technology leader...",
    "titleDescription": "Leads engineering team..."
  }'

Normal Leads Example:

curl -X POST \
  https://sketchief.com/api/generate-opener \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "opener_version": "v2",
    "workflow_type": "normal",
    "userWebsite": "https://yourcompany.com",
    "fullName": "Jane Smith",
    "firstName": "Jane",
    "lastName": "Smith",
    "companyName": "Tech Corp",
    "personalLinkedin": "https://linkedin.com/in/janesmith",
    "website": "https://techcorp.com"
  }'

Response (Save the opener_id):

{
  "success": true,
  "opener_id": "abc123de-456f-7890-gh12-ijklmnopqrst",
  "opener_version": 2,
  "fullName": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "companyName": "Tech Corp",
  "userWebsite": "https://yourcompany.com"
}

Important: Save the opener_id - you'll need it in Step 3 to retrieve your results.

Step 2: Wait

Wait 30-40 seconds for the opener to be generated. The AI is analyzing your company website and creating enhanced personalization.

Step 3: Retrieve Results

Use the GET /get-opener endpoint with your saved opener_id:

curl -X GET \
  "https://sketchief.com/api/get-opener?opener_id=YOUR_OPENER_ID_HERE" \
  -H "X-API-Key: your_api_key_here"

Replace YOUR_OPENER_ID_HERE with the actual opener_id from Step 1.

Response - Completed:

{
  "success": true,
  "status": "completed",
  "opener_id": "YOUR_OPENER_ID_HERE",
  "opener_version": 2,
  "opener": "Hi Jane, I came across...",
  "subjectLine": "Connecting about Tech Corp",
  "fullName": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "companyName": "Tech Corp",
  "email": "jane@techcorp.com",
  "userWebsite": "https://yourcompany.com"
}

Response - Still Processing:

{
  "success": true,
  "status": "processing",
  "opener_id": "YOUR_OPENER_ID_HERE",
  "message": "Opener is still being generated. Check back in a few seconds."
}

Response - Failed:

{
  "success": false,
  "status": "failed",
  "opener_id": "YOUR_OPENER_ID_HERE",
  "error": "Failed to generate opener: insufficient information"
}

Field Reference

Common Fields (All Workflows)

Field Required Description opener_version Optional Set to "v1" or "v2". Defaults to "v1" workflow_type Required Either "salesnav" or "normal" userWebsite Required for V2 Your company website. Must start with https:// or http:// Sales Navigator Fields

Use the exact header names from your Sales Navigator export:

Field Required Description firstName Yes First name of the lead lastName Yes Last name of the lead fullName Yes Full name of the lead companyName Yes Company name regularCompanyUrl No Company's LinkedIn URL industry No Company industry companyLocation No Company location title No Job title summary No Profile summary titleDescription No Job title description Normal Lead Fields

Field Required Description firstName Yes First name of the lead lastName Yes Last name of the lead fullName Yes Full name of the lead companyName Yes Company name personalLinkedin No Lead's LinkedIn profile URL website Conditional* Company website email Conditional* Email address *Either website or email must be provided for normal leads.

Error Responses

401 Unauthorized

Your API key is invalid or has been revoked.

{
  "success": false,
  "error": "Invalid API key"
}

403 Forbidden

API access requires a Business or Enterprise plan.

{
  "success": false,
  "error": "API access requires Business or Enterprise plan",
  "details": {
    "message": "Upgrade to Business plan or higher to access the API"
  }
}

400 Bad Request - Missing Fields

Required fields are missing from your request.

{
  "success": false,
  "error": "Missing required fields: firstName, lastName"
}

400 Bad Request - V2 Website Required

V2 openers require the userWebsite parameter.

{
  "success": false,
  "error": "userWebsite is required for opener_version 'v2'"
}

400 Bad Request - Invalid Website URL

The website URL must start with https:// or http://.

{
  "success": false,
  "error": "userWebsite must start with https:// or http://"
}

402 Payment Required

You don't have enough credits available.

{
  "success": false,
  "error": "Insufficient credits",
  "details": {
    "total": 0,
    "pending": 0,
    "available": 0
  }
}

Code Examples

JavaScript/Node.js - V1 Openers

async function generateV1Opener(leadData) {
  const response = await fetch('https://sketchief.com/api/generate-opener', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workflow_type: 'normal',
      firstName: leadData.firstName,
      lastName: leadData.lastName,
      fullName: leadData.fullName,
      companyName: leadData.company,
      personalLinkedin: leadData.linkedinUrl,
      website: leadData.website
    })
  });
  
  const result = await response.json();
  
  if (result.success) {
    console.log('Subject:', result.subjectLine);
    console.log('Opener:', result.opener);
    return result;
  } else {
    throw new Error(result.error);
  }
}

JavaScript/Node.js - V2 Openers (Async)

async function generateV2Opener(leadData, userWebsite) {
  // Step 1: Generate opener
  const generateResponse = await fetch('https://sketchief.com/api/generate-opener', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      opener_version: 'v2',
      workflow_type: 'normal',
      userWebsite: userWebsite,
      firstName: leadData.firstName,
      lastName: leadData.lastName,
      fullName: leadData.fullName,
      companyName: leadData.company,
      personalLinkedin: leadData.linkedinUrl,
      website: leadData.website
    })
  });
  
  const generateResult = await generateResponse.json();
  
  if (!generateResult.success) {
    throw new Error(generateResult.error);
  }
  
  const openerId = generateResult.opener_id;
  console.log('Opener ID:', openerId);
  
  // Step 2: Wait 35 seconds
  console.log('Waiting 35 seconds for processing...');
  await new Promise(resolve => setTimeout(resolve, 35000));
  
  // Step 3: Retrieve results
  const getResponse = await fetch(
    `https://sketchief.com/api/get-opener?opener_id=${openerId}`,
    {
      headers: {
        'X-API-Key': 'your_api_key_here'
      }
    }
  );
  
  const result = await getResponse.json();
  
  if (result.status === 'completed') {
    console.log('Subject:', result.subjectLine);
    console.log('Opener:', result.opener);
    return result;
  } else if (result.status === 'processing') {
    console.log('Still processing, try again in a few seconds');
    // Implement retry logic here
  } else {
    throw new Error(result.error);
  }
}

Python - V1 Openers

import requests

def generate_v1_opener(lead_data):
    url = 'https://sketchief.com/api/generate-opener'
    headers = {
        'X-API-Key': 'your_api_key_here',
        'Content-Type': 'application/json'
    }
    
    payload = {
        'workflow_type': 'normal',
        'firstName': lead_data['first_name'],
        'lastName': lead_data['last_name'],
        'fullName': lead_data['full_name'],
        'companyName': lead_data['company'],
        'personalLinkedin': lead_data['linkedin_url'],
        'website': lead_data['website']
    }
    
    response = requests.post(url, headers=headers, json=payload)
    result = response.json()
    
    if result['success']:
        print(f"Subject: {result['subjectLine']}")
        print(f"Opener: {result['opener']}")
        return result
    else:
        raise Exception(result['error'])

Python - V2 Openers (Async)

import requests
import time

def generate_v2_opener(lead_data, user_website):
    headers = {
        'X-API-Key': 'your_api_key_here',
        'Content-Type': 'application/json'
    }
    
    # Step 1: Generate opener
    payload = {
        'opener_version': 'v2',
        'workflow_type': 'normal',
        'userWebsite': user_website,
        'firstName': lead_data['first_name'],
        'lastName': lead_data['last_name'],
        'fullName': lead_data['full_name'],
        'companyName': lead_data['company'],
        'personalLinkedin': lead_data['linkedin_url'],
        'website': lead_data['website']
    }
    
    response = requests.post(
        'https://sketchief.com/api/generate-opener',
        headers=headers,
        json=payload
    )
    result = response.json()
    
    if not result['success']:
        raise Exception(result['error'])
    
    opener_id = result['opener_id']
    print(f"Opener ID: {opener_id}")
    
    # Step 2: Wait 35 seconds
    print("Waiting 35 seconds for processing...")
    time.sleep(35)
    
    # Step 3: Retrieve results
    get_response = requests.get(
        f'https://sketchief.com/api/get-opener?opener_id={opener_id}',
        headers={'X-API-Key': 'your_api_key_here'}
    )
    result = get_response.json()
    
    if result['status'] == 'completed':
        print(f"Subject: {result['subjectLine']}")
        print(f"Opener: {result['opener']}")
        return result
    elif result['status'] == 'processing':
        print("Still processing, try again in a few seconds")
        # Implement retry logic here
    else:
        raise Exception(result['error'])

Best Practices

Choosing Between V1 and V2

Use V1 when:

  • You need immediate results
  • You're processing leads in real-time
  • Your integration needs to be simple and fast
  • You don't need company-specific context

Use V2 when:

  • You want maximum personalization
  • You can handle async workflows
  • You're willing to wait 30-40 seconds per lead
  • Your company website provides valuable context

Security

  • Never expose your API key in client-side code (frontend JavaScript, mobile apps)
  • Store API keys in environment variables, not in your code
  • Use different API keys for production and testing
  • Rotate API keys periodically
  • Revoke unused or compromised keys immediately

Rate Limiting

  • The API has rate limits to ensure fair usage
  • If you need higher limits, contact support or upgrade to Enterprise
  • Implement retry logic with exponential backoff for rate limit errors
  • For V2 openers, don't poll too frequently - wait the full 30-40 seconds

Error Handling

Always implement proper error handling:

  • Check for success: false in responses
  • For V2, check the status field (processing, completed, failed)
  • Handle network errors and timeouts
  • Log errors for debugging
  • Show user-friendly messages to your users
  • Don't retry immediately on errors - wait a few seconds

Credit Management

  • Each API call consumes 1 credit regardless of opener version
  • Check your credit balance regularly
  • Implement alerts when credits are running low
  • Track the credits_used in your application

Data Quality

  • Provide as much lead information as possible
  • Always include LinkedIn URLs when available
  • For V2 openers, ensure your userWebsite is accurate and up-to-date
  • Validate data before sending to the API
  • Clean and format data consistently

Integration Use Cases

1. Make.com / n8n Workflows

Perfect for no-code automation:

V1 Flow:

  1. Trigger: New lead added to Google Sheets
  2. HTTP Request: POST to /generate-opener with lead data
  3. Parse response and extract opener and subjectLine
  4. Send to email tool (Instantly, Lemlist, etc.)

V2 Flow:

  1. Trigger: New lead added to Google Sheets
  2. HTTP Request: POST to /generate-opener with opener_version: "v2"
  3. Wait module: 40 seconds
  4. HTTP Request: GET from /get-opener with saved opener_id
  5. Parse response and send to email tool

2. CRM Integration

Automatically generate openers when new leads are added:

  • Trigger: New lead created in CRM
  • Action: Call API with lead data
  • Store opener and subject line in custom CRM fields
  • Use in automated sequences

3. Custom Dashboard

Build your own interface:

  • Import leads through your UI
  • Choose V1 for real-time or V2 for enhanced
  • Display results in your custom format
  • Export to various formats

4. Batch Processing Script

Process large lists:

  • Read leads from CSV
  • For V1: Loop and get immediate results
  • For V2: Generate all openers first, wait, then retrieve all results
  • Compile into output file
  • Import to email tool

Monitoring and Usage

View API Statistics

In the API Keys tab, monitor:

  • Request count for each API key
  • Last used timestamp to see which keys are active
  • Total API calls across all keys

Tracking in Your Application

Consider logging:

  • API call timestamps
  • V1 vs V2 usage
  • Success/failure rates
  • Average response times (V2 will be longer)
  • Credits consumed
  • Error types and frequencies

Credits

Each lead processed via the API consumes 1 credit from your account balance, regardless of opener version (V1 or V2). Make sure you have sufficient credits before making API calls.

All openers generated via the API are automatically saved and can be viewed in the "All Openers" section of your dashboard.

Troubleshooting

"Invalid API key" Error

  • Double-check you copied the full key correctly
  • Make sure the key hasn't been deleted
  • Verify the key is in the X-API-Key header

"Insufficient credits" Error

  • Check your credit balance in the dashboard
  • Upgrade your plan or wait for monthly refill

V2 Opener Stuck in "Processing"

  • Wait the full 30-40 seconds before checking
  • Try checking again after 45-60 seconds
  • If still processing after 2 minutes, contact support

"userWebsite is required" Error

  • V2 openers require the userWebsite parameter
  • Make sure the URL starts with https:// or http://
  • Verify the URL is valid and accessible

Getting Help

View Full Documentation:

  • Click the "Documentation" tab in API Access
  • Reference endpoint details, field requirements, and examples

Contact Support:

  • Business plan: Standard support via email
  • Enterprise plan: Priority support and dedicated account manager

Need Higher Rate Limits?

  • Enterprise plans include higher API limits
  • Contact sales for custom limits

Next Steps: Start testing with V1 openers for immediate results, then try V2 openers when you want enhanced personalization with your company context.

Was this helpful?