> ## 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.

# Integration Notes

> Best practices and important notes for integrating with the Taptalent Partner API

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:

```javascript theme={null}
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:

```json theme={null}
{
  "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 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

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:

```javascript theme={null}
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

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

Use the sandbox environment for development and testing:

* **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

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

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

## Support

If you encounter issues or have questions:

1. Check the [API Reference](/api-reference/overview) for endpoint details
2. Review error messages and status codes
3. Check [Integration Notes](/integration-notes/overview) 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

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](/api-reference/overview) for detailed endpoint documentation
* Set up [Webhooks](/webhooks/overview) for real-time updates
* Follow [Authentication](/authentication/api-keys) best practices