Best practices
Follow these best practices when you integrate the Retrieve 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 single-process polling
#Run only one fetchAssets polling process at a time, so that no process acknowledges a batch that another process hasn't stored.
Recover historical data
#To get asset data again, such as after data loss, follow these practices:
| Best practice | Description |
|---|---|
| Use the right query | Call assetsByTimeRange to get acknowledged assets again. To get new assets, use fetchAssets. |
| Time-based batching | Request one time range at a time, such as one day, and only the range you need to recover. If you omit the start or end date, the query uses the earliest or latest acknowledgment date, respectively. |
| Cursor pagination | Get the next page by passing pageInfo.endCursor as after. Repeat until pageInfo.hasNextPage is false. See the GraphQL Cursor Connections Specification (opens in a new window). |
| Tracking progress | Keep a local record of the time ranges you've recovered, so that you can resume after an interruption. |
Implement polling patterns
#Use these patterns to retrieve new assets:
| Best practice | Description |
|---|---|
| Regular polling | Call fetchAssets every 5 minutes to check for new assets. If your asset volume is low, you can poll less often. |
| Continuous polling | If fetchAssets returns a non-empty token, more assets might be available. Process the batch, then call fetchAssets again right away with the token. Repeat until the token is null or empty. Don't wait for your polling interval between these calls. |
| End of cycle | A null or empty token means that Indeed has delivered all available assets. Wait for your polling interval before you start the next polling cycle. |
| Acknowledgment management | Passing a token to fetchAssets acknowledges that batch, and fetchAssets can't return it again. Store every asset in the batch, or durably record it for retry, before you pass its token. |
Manage assets and workflow
#- Store before you acknowledge: Store every asset in a batch, or durably record it for retry, before you pass its token. See Implement polling patterns.
- Idempotent processing: Use each asset's
idto skip duplicates if you receive the same asset again. Keep every assetidindefinitely, so that you can always recognize a duplicate. - Handle asset types: For the
AtsSyncCandidateSyncAssetinterface, use... oninline fragments for known types and ignore unknown types. A batch can include both Smart Sourcing and Smart Screening assets, and Indeed adds asset types over time. - Apply updates in order: Order Smart Screening updates by
AtsSyncCandidateSyncSmartScreeningUpdate.createdAt, which shows when the update happened. Don't order them byAtsSyncCandidateSyncAssetMetadata.stagedAt, which shows when the asset became available. If you apply updates out of order, older data can overwrite newer data.
Handle files and file downloads
#- Download promptly: File URLs are short-lived presigned URLs (opens in a new window). Download each file as soon as you receive the asset.
- Store files, not URLs: Save each file in your system, not its presigned URL. If a URL expires before you acknowledge its batch, call
fetchAssetsagain without that batch's token to get the assets again. If you've already acknowledged the batch, callassetsByTimeRange, or use anodequery with the asset'sid. - Use file metadata: Use the
nameandcontentTypefields to save and display each file correctly. - Parallel downloads: Download multiple files at the same time to reduce processing time.
Handle errors
#- Exponential backoff: Retry temporary failures with increasing delays and random jitter. If retries fail, stop the polling cycle and resume at the next regular poll. If you haven't stored or durably recorded every asset in the batch, don't pass its token. Call
fetchAssetswithout the token to get the batch again. - Handle partial failures: Plan for batches where some assets are stored and others fail. Don't acknowledge the batch until you store every asset or durably record it for retry, so that a crash or restart doesn't lose the record. To retry a recorded asset after you acknowledge its batch, call
assetsByTimeRangeor use anodequery with the asset'sid.fetchAssetswon't return it again. - Don't acknowledge assets with errors: If the response has a GraphQL error for an asset, don't pass its batch's token, even if you stored the other assets. Call
fetchAssetsagain at the next regular poll to get the batch again. - Robust error handling: Check every response for both HTTP errors and GraphQL errors. See Troubleshoot OAuth errors and Troubleshoot GraphQL errors.
- Set reasonable timeouts: Set appropriate connection and read timeouts.
Optimize performance
#- Batch size: Set a limit that your system can store within your timeouts. Smaller batches reduce repeated work after a failure.
- Caching: Cache employer registration IDs and their
employerIdentifiervalues instead of looking them up repeatedly. Keep cached values for a few hours at most, so that they don't go stale.
Test and monitor
#- Test assets: Call
stageAssetsto create test assets, then retrieve them withfetchAssets. Check themetadata.stagedTestflag to tell test assets from real candidates. Indeed removes test assets after 14 days. - Edge cases: Test mixed batches, unknown asset types, missing optional fields, and out-of-order Smart Screening updates.
- Error scenarios: Test timeouts, network failures, expired presigned URLs, and failures between storing and acknowledging a batch.
- Monitor and alert: Track error rates, response times, assets per polling cycle, time since the last successful poll, and circuit breaker states. Set up alerts.
See also
#Guides
#- Indeed Resource IDs (IRIs) — Look up an entity by its ID with the
nodequery. - Retrieve Candidates API guide — Asset types, requests, and responses.
- Retrieve Candidates API integration guide — Steps to integrate the API.
- Troubleshoot GraphQL errors — Diagnose GraphQL errors returned by the API.
- Troubleshoot OAuth errors — Troubleshoot OAuth errors that can occur before you access Indeed APIs.
References
#- Download and upload objects with presigned URLs (opens in a new window) — How presigned URLs work.
- GraphQL Cursor Connections Specification (opens in a new window) — The pagination model for cursor-based queries.
GraphQL API reference
#assetsByTimeRange— Gets acknowledged assets for a time range.AtsSyncCandidateSyncAsset— The interface that every candidate asset type implements.AtsSyncCandidateSyncAssetMetadata— Metadata for each asset, includingemployerIdentifier,stagedAt, andstagedTest.AtsSyncCandidateSyncSmartScreeningUpdate— A Smart Screening update, includingcreatedAt.EmployerRegistration— An employer registration and its ID.fetchAssets— Gets unacknowledged assets. To acknowledge the previous batch, pass a token.PageInfo— Pagination details, includingendCursorandhasNextPage.stageAssets— Creates test assets for sandbox testing. Mock assets are removed 14 days after staging.