SmartSearch Platform API

Getting Started

The SmartSearch Platform API provides many tools and resources that enable you to integrate with all the powerful capabilities within SmartSearch.

Getting Access

Interested in the SmartSearch Platform API? Contact your Relationship Manager or Support@SmartSearchinc.com to get set up. Once provisioned, refer to the Platform API Launch Guide below to get started.

HTTPS Only

• The API only responds to HTTPS-secured communications
• Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources

Response Format

• The API returns request responses in JSON format
• Error responses return a JSON body containing a status code and a description of what went wrong

Platform API Launch Guide

The launch guide walks you through authenticating with the API and making your first requests across the available resources. It covers everything from obtaining your credentials and generating a token to calling endpoints and interpreting responses.

Download the guide here to get started.

Webhooks

Webhooks allow your application to receive notifications when events occur in SmartSearch. Once configured, SmartSearch will POST to your endpoint whenever a subscribed event fires. If delivery fails, SmartSearch will retry up to 3 times using an exponential backoff strategy.

How to Get Started with Webhooks

1. Discover available events — Call GET /references/webHookEvents to retrieve the full list of supported event types and their corresponding IDs.
2. Request enablement — Contact your Relationship Manager or Support@SmartSearchinc.com and include the specific events you plan to subscribe to. Providing this list upfront ensures only the events relevant to your integration are enabled.
3. Configure your subscriptions — Once enabled, use POST /webhooks to register your endpoint URL for each event, and manage them with the PUT, PATCH, and DELETE endpoints as needed.

For a complete reference of all available webhook events, please refer to the Webhook Event Reference.

Additional Notes

OData & JSON Patch

The GET endpoints in the SmartSearch Platform API follow the OData standard while the PATCH endpoints utilize the JSON Patch format.

Pagination

By default, the Platform API returns 1,000 records at any given time. If there are more than 1,000 results, the response includes an @odata.nextLink value you can call to get the next set of results.

The default page size is an upper bound, not a recommendation. Use $top to request a smaller page and $skip to page through results:

• GET /candidates?$top=100 returns the first 100 records
• GET /candidates?$top=100&$skip=100 returns the next 100
• Continue following @odata.nextLink until it is no longer returned

Field Projection

Use $select to return only the fields your integration actually consumes. Full records carry every available field, and most integrations use a small fraction of them. Projecting fields reduces response size, transfer time and parsing cost on your side.

• GET /candidates?$select=candidateNum,candidateFirstName,candidateLastName,candidateStatusCode
• Combine with pagination: GET /candidates?$top=100&$select=candidateNum,candidateStatusCode

Timestamps

All incoming timestamps must follow the ISO 8601 format. If no timezone is specified, UTC is assumed by default. Below are examples of valid formats:

• UTC timestamp: 2024-08-15T14:30:00Z
• Date-only format: 2024-08-15