Integration Notes

This guide covers best practices, common patterns, and important considerations when integrating with the Taptalent Partner API.

Supported Integration Patterns

One-Way Ingestion

Create jobs in TapTalent from your internal systems:

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

Event-Driven Orchestration

Configure webhooks to trigger actions in your system:

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

Error Handling

Always implement robust error handling in your integration. The TapTalent API uses a structured error format:

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

All errors follow this format:

{
  "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

When syncing data between systems:

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

For candidate resume uploads, use the bulk upload endpoint:

Upload up to 200 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

Rate limits are applied at the company level. To avoid hitting limits:

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

Observability & Monitoring

Recommended Logging Practices

Log all API interactions with appropriate detail:

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

Implement comprehensive error tracking:

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

Problem: Creating the same job multiple times Solution:

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

Status Desynchronization

Problem: Job status differs between systems Solution:

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

Improper Error Retries

Problem: Retrying non-retryable errors Solution:

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

Problem: Using wrong API key or inactive keys Solution:

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

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

Testing

Test Environment

Use the sandbox environment for development and testing:

Sandbox Base URL: https://sandbox.partner-api.taptalent.io/v1
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

Use mock data for local development to avoid unnecessary API calls:

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

Support

If you encounter issues or have questions:

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

Versioning

The API is versioned. Always specify the version in your requests:

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

Breaking changes will be introduced in new versions with advance notice.

Next Steps

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

Getting Started