API Documentation

API Overview

The SkillSync AI API is a powerful RESTful API that allows you to integrate our intelligent talent matching platform into your applications. Access our advanced AI algorithms, manage user profiles, facilitate connections, and build amazing experiences.

Base URL

https://api.skillsync.ai/v1

Key Features

AI-Powered Matching: Access our advanced algorithms for talent discovery
Real-time Communication: Enable instant messaging between users
Profile Management: Complete CRUD operations for user profiles
Analytics & Insights: Detailed metrics and performance data
Webhook Support: Real-time event notifications
Enterprise Security: OAuth 2.0 and API key authentication

Response Format

All API responses are returned in JSON format with consistent structure:

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Operation completed successfully",
  "meta": {
    "timestamp": "2025-01-20T10:42:00Z",
    "version": "v1.0",
    "request_id": "req_abc123"
  }
}

Authentication

SkillSync AI supports multiple authentication methods to secure your API access:

API Key Authentication

Include your API key in the Authorization header for all requests:

curl -H "Authorization: Bearer sk_live_abc123..." \
     -H "Content-Type: application/json" \
     https://api.skillsync.ai/v1/profiles

OAuth 2.0 (Enterprise)

For enterprise applications requiring user-specific access:

curl -H "Authorization: Bearer oauth_token_here" \
     -H "Content-Type: application/json" \
     https://api.skillsync.ai/v1/matches

Getting Your API Key

Create your SkillSync AI developer account
Navigate to your dashboard
Go to Settings → API Keys
Generate a new API key with appropriate permissions
Store your key securely and never expose it in client-side code

POST

Generate API Key

Create a new API key with specific permissions and scopes.

POST /auth/api-keys

Request Body

{
  "name": "Production API Key",
  "scopes": ["matches:read", "profiles:write", "messages:read"],
  "expires_at": "2025-12-31T23:59:59Z"
}

Rate Limits

To ensure fair usage and optimal performance, our API implements rate limiting based on your subscription plan:

Plan	Requests/Min	Requests/Day	Burst Limit	Concurrent Requests
Free	60	1,000	100	5
Pro	300	10,000	500	20
Enterprise	1,000	50,000	2,000	100
Custom	Unlimited*	Unlimited*	Custom	Custom

*Subject to fair usage policy

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1642780800
X-RateLimit-Retry-After: 60

API Endpoints

Matches API

The Matches API powers our core talent matching functionality using advanced AI algorithms.

GET

Get Matches

Retrieve intelligent matches for a specific user based on their profile, preferences, and our AI matching algorithms.

GET /matches/:userId

Path Parameters

Parameter	Type	Required	Description
`userId`	string	Required	Unique user identifier (UUID format)

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of matches to return (default: 20, max: 100)
`min_score`	integer	Optional	Minimum match score threshold (default: 60, range: 0-100)
`skills`	array	Optional	Filter matches by specific skills
`location`	string	Optional	Filter by location (city, country, or "remote")
`experience_level`	string	Optional	junior, mid, senior, lead

Example Request

curl -H "Authorization: Bearer sk_live_abc123..." \
  "https://api.skillsync.ai/v1/matches/user_456?limit=10&min_score=80&skills[]=React&skills[]=Node.js"

Example Response

{
  "success": true,
  "data": {
    "matches": [
      {
        "id": "match_123",
        "user_id": "user_789",
        "profile": {
          "name": "TechStart Inc.",
          "type": "startup",
          "logo": "https://cdn.skillsync.ai/logos/techstart.png",
          "location": "Remote",
          "company_size": "11-50",
          "industry": "Technology"
        },
        "match_score": 92,
        "match_reasons": [
          "Strong skill alignment in React and Node.js",
          "Similar project experience",
          "Compatible work style preferences"
        ],
        "skills_matched": [
          { "skill": "React", "weight": 0.9 },
          { "skill": "Node.js", "weight": 0.85 },
          { "skill": "TypeScript", "weight": 0.75 }
        ],
        "compatibility_scores": {
          "technical": 95,
          "cultural": 88,
          "experience": 90
        },
        "created_at": "2025-01-20T10:42:00Z",
        "expires_at": "2025-01-27T10:42:00Z"
      }
    ],
    "pagination": {
      "total": 156,
      "page": 1,
      "per_page": 10,
      "total_pages": 16
    },
    "filters_applied": {
      "min_score": 80,
      "skills": ["React", "Node.js"]
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:42:00Z",
    "request_id": "req_abc123"
  }
}

POST

Create Match Action

Accept, reject, or save a match for later consideration.

POST /matches/:matchId/action

Request Body

{
  "action": "accept", // "accept", "reject", "save"
  "message": "I'm really excited about this opportunity! When can we schedule a call?",
  "metadata": {
    "priority": "high",
    "notes": "Perfect fit for our React team"
  }
}

Response

{
  "success": true,
  "data": {
    "action_id": "action_123",
    "match_id": "match_456",
    "status": "accepted",
    "conversation_id": "conv_789",
    "next_steps": [
      "Wait for response from TechStart Inc.",
      "Check your messages for updates",
      "Complete your profile for better matches"
    ]
  }
}

GET

Get Match Details

Retrieve detailed information about a specific match including AI insights.

GET /matches/:matchId

Profiles API

Manage user profiles, skills, preferences, and career information.

GET

Get Profile

Retrieve complete profile information for a user.

GET /profiles/:userId

Example Response

{
  "success": true,
  "data": {
    "id": "user_123",
    "name": "Sarah Johnson",
    "title": "Full Stack Developer",
    "avatar": "https://cdn.skillsync.ai/avatars/user_123.jpg",
    "bio": "Passionate developer with 4+ years building scalable web applications...",
    "location": "San Francisco, CA",
    "remote_work": true,
    "experience_years": 4,
    "skills": [
      { "name": "React", "level": "expert", "years": 3 },
      { "name": "Node.js", "level": "advanced", "years": 2 },
      { "name": "Python", "level": "intermediate", "years": 1 }
    ],
    "preferences": {
      "role_types": ["full-time", "contract"],
      "company_sizes": ["startup", "small"],
      "industries": ["technology", "healthcare"],
      "salary_range": { "min": 80000, "max": 120000, "currency": "USD" }
    },
    "social_links": {
      "github": "https://github.com/sarahjohnson",
      "linkedin": "https://linkedin.com/in/sarahjohnson",
      "portfolio": "https://sarahjohnson.dev"
    },
    "verification": {
      "email": true,
      "phone": true,
      "github": true,
      "linkedin": false
    },
    "created_at": "2024-06-15T08:30:00Z",
    "updated_at": "2025-01-15T14:22:00Z"
  }
}

PUT

Update Profile

Update user profile information with validation and AI optimization suggestions.

PUT /profiles/:userId

Request Body

{
  "name": "Sarah Johnson",
  "title": "Senior Full Stack Developer",
  "bio": "Experienced full-stack developer specializing in React and Node.js...",
  "location": "Remote",
  "skills": [
    { "name": "React", "level": "expert", "years": 4 },
    { "name": "TypeScript", "level": "advanced", "years": 2 }
  ],
  "preferences": {
    "role_types": ["full-time"],
    "salary_range": { "min": 90000, "max": 130000, "currency": "USD" }
  }
}

POST

Upload Profile Photo

Upload a profile photo with automatic optimization and moderation.

POST /profiles/:userId/photo

Messages API

Real-time messaging system for communication between matched users.

POST

Send Message

Send a message to another user in an existing conversation or start a new one.

POST /messages

Request Body

{
  "recipient_id": "user_456",
  "message": "Hi! I saw your profile and I'm really interested in discussing the React developer position at your startup.",
  "type": "text", // "text", "image", "file", "audio"
  "metadata": {
    "match_id": "match_123",
    "thread_id": "thread_789"
  }
}

Response

{
  "success": true,
  "data": {
    "message_id": "msg_123",
    "conversation_id": "conv_456",
    "status": "sent",
    "delivered_at": "2025-01-20T10:42:00Z",
    "read_receipt_enabled": true
  }
}

GET

Get Conversations

Retrieve all conversations for a user with pagination and filtering.

GET /messages/conversations

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of conversations (default: 20, max: 100)
`unread_only`	boolean	Filter to show only unread conversations
`search`	string	Search conversations by participant name or company

GET

Get Conversation Messages

Retrieve messages from a specific conversation with real-time updates.

GET /messages/conversations/:conversationId

Analytics API

Access detailed analytics and insights about user engagement, match success rates, and platform performance.

GET

Get User Analytics

Comprehensive analytics for user performance and engagement metrics.

GET /analytics/users/:userId

Example Response

{
  "success": true,
  "data": {
    "profile_views": {
      "total": 1247,
      "this_week": 89,
      "growth": "+12%"
    },
    "matches": {
      "total_received": 156,
      "accepted": 23,
      "acceptance_rate": "14.7%",
      "avg_match_score": 78
    },
    "messages": {
      "sent": 45,
      "received": 67,
      "response_rate": "85%",
      "avg_response_time": "2h 15m"
    },
    "skills_trending": [
      { "skill": "React", "demand_score": 95 },
      { "skill": "TypeScript", "demand_score": 87 }
    ]
  }
}

GET

Get Platform Analytics

Platform-wide analytics and market insights (Enterprise only).

GET /analytics/platform

Webhooks

SkillSync AI can send real-time webhooks to notify your application of important events. Webhooks are HTTP POST requests sent to your specified endpoint.

Setting Up Webhooks

Navigate to your dashboard → Webhooks
Add your webhook endpoint URL
Select the events you want to receive
Configure your secret key for security
Test your webhook endpoint

Supported Events

Event	Description	Payload
`match.created`	New match found for user	Match object with details
`match.accepted`	Match accepted by user	Match and action details
`match.rejected`	Match rejected by user	Match and rejection reason
`message.received`	New message received	Message content and metadata
`profile.updated`	Profile information updated	Updated profile fields
`conversation.started`	New conversation initiated	Conversation participants and metadata

Webhook Payload Structure

{
  "id": "evt_1234567890",
  "event": "match.created",
  "data": {
    "match_id": "match_123",
    "user_id": "user_456",
    "matched_user_id": "user_789",
    "match_score": 92,
    "skills_matched": ["React", "Node.js", "TypeScript"],
    "timestamp": "2025-01-20T10:42:00Z",
    "expires_at": "2025-01-27T10:42:00Z"
  },
  "webhook_id": "wh_abcdef123456",
  "created_at": "2025-01-20T10:42:00Z",
  "signature": "sha256=abc123def456..."
}

Webhook Security

Verify webhook authenticity using HMAC signature:

// Node.js example
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  const expected = `sha256=${digest}`;
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'utf8'),
    Buffer.from(expected, 'utf8')
  );
}

Webhook Retry Policy

Webhooks are retried up to 5 times with exponential backoff
Initial retry after 1 second, then 2s, 4s, 8s, 16s
Webhooks are considered failed after 5 unsuccessful attempts
You can view failed webhooks in your dashboard

SDKs & Libraries

Official SDKs and community libraries to integrate SkillSync AI into your applications with ease.

JavaScript / Node.js

Official JavaScript SDK for web and Node.js applications with TypeScript support.

npm install @skillsync/api-client

// Usage example
import SkillSync from '@skillsync/api-client';

const client = new SkillSync({
  apiKey: 'sk_live_abc123...'
});

const matches = await client.matches.get('user_123');

Python

Python SDK perfect for backend integrations, data analysis, and machine learning workflows.

pip install skillsync-python

# Usage example
from skillsync import SkillSyncClient

client = SkillSyncClient(api_key='sk_live_abc123...')
matches = client.matches.get(user_id='user_123')

React

React components and hooks for seamless frontend integration with built-in state management.

npm install @skillsync/react

// Usage example
import { SkillSyncProvider, useMatches } from '@skillsync/react';

function MatchesList() {
  const { matches, loading } = useMatches();
  return {/* Your UI here */}
;
}

PHP

PHP library for server-side integrations with Laravel and Symfony support.

composer require skillsync/php-sdk

// Usage example
$client = new SkillSync\Client(['api_key' => 'sk_live_abc123...']);
$matches = $client->matches->get('user_123');

Android

Android SDK for native mobile applications with offline support and caching.

implementation 'ai.skillsync:android-sdk:1.0.0'

// Usage example
SkillSyncClient client = new SkillSyncClient("sk_live_abc123...");
client.getMatches("user_123", new MatchesCallback() { ... });

iOS

Swift SDK for iOS applications with SwiftUI support and reactive programming patterns.

pod 'SkillSyncSDK'

// Usage example
let client = SkillSyncClient(apiKey: "sk_live_abc123...")
client.getMatches(userId: "user_123") { matches in ... }

Community SDKs

Community-maintained libraries for additional programming languages:

Ruby: gem install skillsync-ruby
Go: go get github.com/skillsync/go-sdk
.NET: dotnet add package SkillSync.SDK
Java: Available via Maven Central

Error Handling

SkillSync AI uses standard HTTP status codes and provides detailed error messages to help you debug issues quickly.

HTTP Status Codes

Status Code	Meaning	Description	Action Required
200	Success	Request completed successfully	None
201	Created	Resource created successfully	None
400	Bad Request	Invalid request parameters or body	Check request format
401	Unauthorized	Invalid or missing API key	Verify API key
403	Forbidden	Access denied to resource	Check permissions
404	Not Found	Resource does not exist	Verify resource ID
422	Unprocessable Entity	Validation errors in request data	Fix validation errors
429	Too Many Requests	Rate limit exceeded	Implement rate limiting
500	Internal Server Error	Server error occurred	Contact support
503	Service Unavailable	Temporary service disruption	Retry with backoff

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": {
      "field": "email",
      "issue": "invalid_email_format",
      "provided": "invalid-email",
      "expected": "Valid email address"
    },
    "suggestion": "Please provide a valid email address in the format: user@example.com"
  },
  "meta": {
    "timestamp": "2025-01-20T10:42:00Z",
    "request_id": "req_abc123",
    "documentation": "https://docs.skillsync.ai/errors#validation_error"
  }
}

Common Error Codes

Error Code	Description	Resolution
`INVALID_API_KEY`	API key is invalid or expired	Generate a new API key
`RATE_LIMIT_EXCEEDED`	Too many requests sent	Implement exponential backoff
`VALIDATION_ERROR`	Request data validation failed	Fix the specified validation errors
`RESOURCE_NOT_FOUND`	Requested resource doesn't exist	Verify the resource ID
`INSUFFICIENT_PERMISSIONS`	API key lacks required permissions	Request additional scopes

Best Practices for Error Handling

Always check the HTTP status code before processing the response
Implement exponential backoff for 429 and 5xx errors
Log error details including the request_id for support inquiries
Handle network timeouts gracefully with appropriate retry logic
Validate input data before sending requests to minimize 400 errors

API Overview

Base URL

Key Features

Response Format

Authentication

API Key Authentication

OAuth 2.0 (Enterprise)

Getting Your API Key

Generate API Key

Request Body

Rate Limits

Rate Limit Headers

API Endpoints

Matches API

Get Matches

Path Parameters

Query Parameters

Example Request

Example Response

Create Match Action

Request Body

Response

Get Match Details

Profiles API

Get Profile

Example Response

Update Profile

Request Body

Upload Profile Photo

Messages API

Send Message

Request Body

Response

Get Conversations

Query Parameters

Get Conversation Messages

Analytics API

Get User Analytics

Example Response

Get Platform Analytics

Webhooks

Setting Up Webhooks

Supported Events

Webhook Payload Structure

Webhook Security

Webhook Retry Policy

SDKs & Libraries

JavaScript / Node.js

Python

React

PHP

Android

iOS

Community SDKs

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Best Practices for Error Handling

Ready to Build Something Amazing?

Developer Login

Get API Access