Best practices

Best practices for the Send Candidates API.

 

legal notice

By using this API and its documentation and building an integration, you agree to the Additional API Terms and Guidelines.

Implement application-level locking

Implement application-level locking in your system to ensure only one operation occurs per application at a time. This ensures that the last version you submit is the active version published to Indeed.

Sync historical data

When you integrate with the Send Candidates API, use these approaches to sync historical application data:

Sync historical data best practices

Best practice	Description
Phased implementation	Start with a small subset of recent applications, such as the last 30–90 days, before syncing older data.
Time-based batching	Process historical applications in batches by time period, such as monthly cohorts.
Prioritization strategy	Begin with most recent applications and work backward.
Rate management	For large volumes, distribute historical sync over longer periods. Schedule bulk processing during off-peak hours.
Tracking progress	Maintain a local record of synced applications. Record the timestamp of the last successful sync by employer and job. Implement the ability to resume after interruptions.

Implement sync patterns

After you sync historical data, implement these patterns:

Sync patterns best practices

Best practice	Description
Real-time updates	Send application and status changes as they occur in your system. Provide all application data on every update.
Periodic polling	Check your system every 15–30 minutes for new or updated applications.
Webhook-driven	If your system supports webhooks, trigger API calls when application events occur.
Sync state management	Record the last sync timestamp for each employer. Implement cursor-based syncing using application update timestamps. Periodically reconcile data with verification checks.

Manage applications and workflow

• Version control: Track application versions for auditing.
• Application data: Send all application data with every update.
• Complete within timeout: Upload and submit within 5 minutes of initialization.
• Sequential processing: Do not run concurrent operations on the same application identity.

Handle files and file uploads

• Pre-calculate MD5: Calculate checksums before initialization to ensure consistency.
• Validate file size: Check file sizes before initialization to avoid exceeding the 15MB limit.
• Resume handling: Ensure only one attachment has type RESUME for proper parsing.
• Parallel uploads: Upload multiple attachments concurrently (but respect rate limits).

Handle errors

• Use exponential backoff with jitter for transient failures.
• Implement circuit breakers to prevent cascading failures.
• Design for partial failures where some operations succeed and others fail.
• Check GraphQL responses for both HTTP-level and GraphQL-specific errors.
• Set reasonable connection and read timeouts.

For common errors and resolution steps, see Troubleshoot Send Candidates API errors.

Optimize performance

• Batch operations: Use filter parameters to query multiple application versions at once.
• Caching: Cache employer registration and job IDs to reduce lookup overhead.

Implement security and protect data

• Data validation: Validate all input data client-side before making API calls (validate early).
• PII handling: Ensure proper encryption and handling of candidate personal information.
• Audit logging: Log all application operations with correlation IDs for troubleshooting.

Test and monitor

• Edge cases: Test with maximum file sizes, special characters in names, and various file types.
• Error scenarios: Test timeout handling, network failures, and invalid data scenarios.
• Monitor and alert: Track error rates, response times, and circuit breaker states.

 

Was this page helpful?