Integration Notes

Documentation Index

Fetch the complete documentation index at: https://docs.taptalent.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Supported Integration Patterns

​

One-Way Ingestion

• Sync job postings from your ATS or HRIS
• Automatically create jobs when positions open
• Keep job data synchronized

​

Event-Driven Orchestration

• Receive notifications when jobs are created or updated
• Trigger workflows based on job status changes
• Keep systems in sync without polling

​

Error Handling

try {
  const response = await fetch('https://partner-api.taptalent.io/v1/partner/jobs', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(jobData)
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    // Handle specific error codes
    if (response.status === 401 || response.status === 403) {
      // Authentication error - check API key
      console.error('Authentication failed:', error.message);
    } else if (response.status === 400) {
      // Validation error - check error.details
      console.error('Validation errors:', error.error?.details);
    } else if (response.status === 403 && error.code === 'ACCOUNT_INACTIVE') {
      // Subscription inactive
      console.error('Subscription inactive:', error.message);
    }
    
    throw new Error(error.error?.message || 'API request failed');
  }
  
  const data = await response.json();
  return data;
} catch (error) {
  // Log and handle error appropriately
  console.error('API Error:', error);
  throw error;
}

​

Error Response Structure

{
  "error": {
    "code": "ERROR_CODE",
    "type": "error_type",
    "message": "Human-readable error message",
    "details": {
      "field": "Specific validation error message"
    }
  }
}

​

Common Error Codes

• INVALID_REQUEST: Validation error - check details for field-specific errors
• ACCOUNT_INACTIVE: Subscription is inactive - renew subscription
• FORBIDDEN: Insufficient permissions
• INTERNAL_ERROR: Server error - contact support

​

Data Ownership & Source of Truth

​

Recommended Ownership Models

• TapTalent as Source of Truth: Create jobs in TapTalent and sync to your systems
• Your System as Source of Truth: Create jobs in your system and sync to TapTalent
• Bi-directional Sync: Keep both systems in sync (requires careful conflict resolution)

​

Conflict Resolution

• Use timestamps to determine the most recent update
• Implement idempotency keys to prevent duplicate operations
• Handle conflicts gracefully with clear resolution strategies

​

High-Volume Considerations

​

Batch Operations

• Upload up to 5,000 resumes per batch
• Receive webhook notifications when processing starts/completes
• Retrieve parsed candidates using pagination
• Process batches asynchronously and handle webhook events

​

Throughput Optimization

• Make requests in parallel when possible
• Implement connection pooling
• Cache frequently accessed data
• Use webhooks instead of polling

​

Rate Limiting

• Implement exponential backoff for retries
• Monitor your API usage
• Distribute requests over time for high-volume operations

​

Observability & Monitoring

​

Recommended Logging Practices

const logApiCall = (endpoint, method, status, duration) => {
  console.log({
    timestamp: new Date().toISOString(),
    endpoint,
    method,
    status,
    duration,
    // Include request/response details (sanitize sensitive data)
  });
};

​

Tracking Failed API Calls

• Log all failed requests with error details
• Track error rates and patterns
• Set up alerts for unusual error rates
• Monitor API key status and subscription status

​

Metrics to Track

• API call success rate
• Average response time
• Error rate by error code
• API key usage and status
• Webhook delivery success rate (when available)

​

Common Pitfalls

​

Duplicate Job Creation

• Implement idempotency checks
• Use unique identifiers from your system
• Check if job exists before creating

​

Status Desynchronization

• Use webhooks to receive status updates (when available)
• Implement periodic sync jobs
• Track last sync timestamp

​

Improper Error Retries

• Only retry 5xx errors and rate limit errors (429)
• Don’t retry 4xx errors (except 429)
• Implement exponential backoff
• Set maximum retry limits

​

API Key Management Issues

• Use environment variables for API keys
• Implement key rotation procedures
• Monitor API key status
• Have fallback keys for critical operations

​

Security Best Practices

​

API Key Storage

• Never commit API keys to version control
• Use environment variables or secure secret management
• Rotate keys regularly
• Use different keys for different environments

​

Webhook Security

• Always use HTTPS for webhook endpoints
• Verify webhook signatures (when available)
• Implement idempotency checks
• Rate limit webhook endpoints

​

Request Validation

• Validate all input data before sending to API
• Sanitize sensitive data in logs
• Implement request timeouts
• Use connection pooling

​

Performance Tips

1. Use Appropriate Request Sizes: Balance between too many requests and too much data per request
2. Implement Caching: Cache job data that doesn’t change frequently
3. Use Webhooks: Prefer webhooks over polling when available
4. Parallel Requests: Make independent requests in parallel when appropriate
5. Connection Reuse: Reuse HTTP connections when possible

​

Testing

​

Test Environment

• Sandbox Base URL: https://sandbox.partner-api.taptalent.io/v1/partner
• Use test API keys (prefixed with sk_test_) with the sandbox environment
• Test all integration flows
• Verify error handling
• Test edge cases and validation

​

Mock Data

const mockJobResponse = {
  id: "mock-job-id",
  title: "Test Job",
  status: "DRAFT",
  // ... other fields
};

​

Support

1. Check the API Reference for endpoint details
2. Review error messages and status codes
3. Check Integration Notes for common issues
4. Contact support with:
   • API endpoint you’re calling
   • Request/response details (sanitize sensitive data)
   • Error messages or logs
   • Steps to reproduce

​

Versioning

https://partner-api.taptalent.io/v1/partner/jobs

​

Next Steps

• Review the API Reference for detailed endpoint documentation
• Set up Webhooks for real-time updates
• Follow Authentication best practices