Status Page
Documentation

LENS API Guide v2.0

Suggest Edits

LENS API v2.0

Overview

Lightcast provides several API's for clients to parse resumes and job postings. There are some customers who are using API hosted in Lightcast data centers to access LENS products. Some of the customers are using web service API's to access LENS products instances hosted in their own data centers.

LENS Api designed as highly scalable, cross platform, multi-tenant architecture hosted at Lightcast data center. It offers clients to access its resources through both REST and SOAP protocols.

LENS products that are available via SaaS:

  • LENS xray
  • LENS optic jobs
  • LENS optic resumes
  • LENS spectrum

Getting Started

Get API Access Credentials

LENS api is highly secured and you need security credentials to access the API. You can find the details under the Profile -> OAuth Settings after you log in to the Lens API portal.

In order to access any protected resources of Parse api, you need the following four details.

  1. Consumer key
  2. Consumer secret
  3. Parse Api Access Token
  4. Parse Api Access Token Secret

To access resources of Search api, you need the following four details.

  1. Consumer key
  2. Consumer secret
  3. Search Api Access Token
  4. Search Api Access Token Secret

Take note of the all details as you'll need to add it to your code later.

Create Authorization Header

Download OAuthGeneration library from Lens API portal and add it to your application. You can generate the authorization header using the OAuthGeneration library as like the following.

OAuthGeneration oAuth = new OAuthGeneration("WEB_SERVICE_URL", "HTTP_METHOD", "CLIENT_ID", "CLIENT_SECRET", "API_ACCESS_TOKEN", "API_ACCESS_TOKEN_SECRET");

String oAuthString = oAuth.GetOAuthString();

string oAuthString = OAuthGeneration.OAuth.GetOAuthString("WEB_SERVICE_URL", "HTTP_METHOD", "CLIENT_ID", "CLIENT_SECRET", "API_ACCESS_TOKEN", "API_ACCESS_TOKEN_SECRET");

$oAuth = new OAuthGeneration("WEB_SERVICE_URL", "HTTP_METHOD", "CLIENT_ID", "CLIENT_SECRET", "API_ACCESS_TOKEN", "API_ACCESS_TOKEN_SECRET");

$oAuthString = $oAuth->GetOAuthString();

oAuth = OAuthGeneration("WEB_SERVICE_URL", "HTTP_METHOD", "CLIENT_ID", "CLIENT_SECRET", "API_ACCESS_TOKEN", "API_ACCESS_TOKEN_SECRET")

oAuthString = oAuth.GetOAuthString()

Use the OAuth header generator to create authorization header from command line.

Prepare Request Data

To parse/search with LENS api, you need to create request data in certain format. The Parse API and Search API page contains reference to the different parse/search api endpoints including request and response data samples.

Request & Response Formats

LENS api accepts both XML and JSON formatted input data. You need to add the content-type header in HTTP request to specify the format of input request data.

You need to add the Accept header to specify the api regarding the format of response. You can receive either XML or JSON formatted response from LENS api based on the Accept header.

Use application/xml for XML and application/json for JSON formatted request/response data.

Connect to LENS api

You need to send HTTP request to parse/search endpoint added with all the necessary details including the following,

  • Authorization header
  • Content-Type & Accept Header
  • URL to which the request needs to be sent
  • Input request Data
    Following is the sample code to send HTTP request to LENS api.

Download LensApiClient library from Lens API portal and add it to your application. You can communicate with LENS api using the LensApiClient library as like the following.

LensApiClient apiClient = new LensApiClient();

String response = apiClient.sendLensApiRequest("WEB_SERVICE_URL", "HTTP_METHOD", oAuthString, "ContentType", "AcceptType", "REQUEST_BODY");

Accessing the Response Data

The standard api response includes the following,

RequestIdUnique id for each request. This id can be used to query the the api logs.
TimestampTimestamp in UNC format the request was made (Ex. 2020-12-12 22:36:45.220)
StatusSuccess/Failure status of the request
StatusCodeHTTP response status code. Refer the Best practices page for more details about the possible status codes.
ResponseDataAn object containing the parse/search response. It can be either the successful parse/search response or error message in case of failed requests. You need to refer the documentation page for more details about the response object structure

Next Steps

Download the sample code from Lens API portal.

Before running the sample, you need to make sure that the following details are updated.

WEB_SERVICE_URLREST/SOAP URL
HTTP_METHODHTTP method
CLIENT_IDConsumer key
CLIENT_SECRETConsumer secret
API_ACCESS_TOKENParse/Search api access token(Based on the api which you are going to use)
API_ACCESS_TOKEN_SECRETParse/Search api access token secret(Based on the api which you are going to use)
CONTENT_TYPEapplication/xml or application/json
ACCEPT_TYPEapplication/xml or application/json
REQUEST_BODYXML/JSON formatted data to be posted to LENS api

Note:

For SOAP request CONTENT_TYPE and ACCEPT_TYPE should be empty string (" ").

Authentication details can be found in OAuth page.

Features

Resume Parsing

Parse data into different file formats.

  • Full resume output marked up as structured data in HR-XML, document oriented BGT XML, or JSON
  • Retrieve specific fields from resumes, including contact, statements, skills, professional, education, summary, experience, references, and the summary sections SkillRollUp and DataElementsRollup
  • Full resume parsing output in structured formats:
    • RTF formatted resume along with BGT XML
    • HTML formatted resume along with BGT XML
  • Locale identification - identifies the locale of the resume with or without parsing
  • Auto locale detection-based resume parsing - automatically identifies the locale of the resume and sends the resume for parsing to the parser handling that locale
  • Supports DOC, DOCX, HTML, RTF, PDF, ODT, TXT, WPD, and WPS file formats for resume parsing
  • Supports LENS optic parsing and metadata coding of resumes in the United States, United Kingdom, Australia, New Zealand and Canada locales
  • LENS xray supports 55 locales for resume parsing.
  • Supports HR-XML 2.5 output

Job Parsing

Parses different file format of job.

  • Full job output marked up as structured data in document oriented BGTXML or JSON
  • Retrieve specific fields from job including background, contact, duties, SkillRollUp, DataElementsRollup and the summary sections
  • Full job parsing output in structured formats:
    • RTF formatted job along with BGT XML
    • HTML formatted job along with BGT XML
  • Process Locale - identifies the locale of a Job
  • Auto Locale detection based job parsing - automatically identifies the locale of job and parses it with the parser of specific locale
  • Supports DOC, DOCX, HTM, HTML, RTF, PDF, ODT, TXT, WPD, WPS file formats for job parsing
  • LENS Optic parsing and metadata coding of jobs for the United States, United Kingdom, Australia, New Zealand and Singapore locales

Resume Search

Search resumes with provided search criteria.

  • Register resume - Stores resumes into search repository
  • Unregister resume - Deletes or removes resume from the search repository based on its registered id.
  • Search resume - Performs search based on the resumes stored in repository.
    • Keyword Search
    • AI Search - resume vs resume, job vs resume
    • Faceted Search
    • Search by Geography
    • Search by Experience
    • Search by Custom Filters
  • Fetch Resume - Retrieve specific resume from the search repository and provide the candidate's full resume to view at any time

Job Search

Search jobs with provided search criteria.

  • Register job - Stores job into search repository
  • Unregister job - Deletes or removes a job from the search repository based on its registered id
  • Search job - Performs search based on the job stored in a repository.
    • Keyword Search
    • AI Search - job vs job, resume vs jobs
    • Faceted Search
    • Search by Geography
    • Search by Experience
    • Search by Custom Filters
  • Fetch job - Retrieve specific job from the search repository and provide the full jobs to view at any time.

Authentication

API Authentication Using OAuth v1.0

Overview

Every call to the Lightcast APIs is authenticated using the OAuthv1.0 standard. This means that each HTTP request to the APIs needs to include an OAuth header using information provided by Lightcast.

The OAuth Consumer Key("OAuth_consumer_key") maps to a client and the OAuth Token ("OAuth_token") maps to the API being accessed. This means that all requests are automatically put into the scope of the client so that, for example, a GET request to the URI would ensure that the results are for the client specified by the OAuth Consumer Key.

We support both HMAC-SHA1 and RSA-SHA1as OAuth signature encryption. We do not support PLAINTEXT signature encryption.

To know more about authentication and how to get the access token, visit the page OAuth 1.0

Errors

Checking for Errors

If you encounter an error while accessing LENS api, please find explanations for the errors in Error Codes.

Supported HTTP Response Codes

When an error is encountered, you'll receive an appropriate HTTP response code (for example 400 for "Bad Request".) You'll also get details returned to you in the body of the response.

STATUS CODEDESCRIPTION
200 (OK)Request was successful.
400 (Bad Request)Invalid format for your request. Make sure you're passing in the correct parameters.
401 (Unauthorized)Not authorized to make this request. Checks the API documentation to be sure that you have access to the API or portion of the API you're making a request to.
404 (Not Found)The requested resource could not be found. Check spelling and review the API documentation.
500 (Internal Server Error)Server side error processing request. Please try again later.

OAuth Token / API Key Security

OAuth access tokens or API keys should be treated as secret data and not exposed to users. To ensure the security of your OAuth access token or API key, we strongly suggest that you make requests to the LENS api server-side whenever possible.

Any requests to the LENS API made via client-side JavaScript present the risk of your OAuth token or API key being compromised.The consumer secrets are plain text and using client side script to generate OAuth signature can make the secrets to be visible to customers while using the client application.We would like to recommend users to use any server side script to communicate with our api instead of using JavaScript or ajax based communication.

If you have any specific questions about LENS API key and access token security, please don't hesitate to contact us at [email protected].

Models

Parse API Models

Parse API Models consists the Parse API Response and the Enumeration values.

  • Response
  • Enum
  • InstanceType
  • Locale
  • Resume Fields
  • Job Fields

Search API Models

Search API Models consists the Search API Response and the Enumeration values.

  • Response
  • Enum
  • InstanceType
  • Locale
  • Error On Duplicate or Overwrite
  • Keyword Search Type
  • Keyword Context
  • Keyword Logical Operator
  • Distance Units
  • Include Unknown
  • Sort
  • Vendor Type
  • Vendor Status

APIs

Parse

Parse API offers resume and Job parsing features(includes support for locale detection based parsing). It parses data into different file formats of resumes/jobs. Supports DOC, DOCX, HTML, RTF, PDF, ODT, TXT, WPD, and WPS file formats for resume/job parsing.

Search

Search API offers search and match features of resume/job. Search resumes/jobs are provided with search criteria's. Provides the functionality to create/delete/retrieve/search/fetch resumes and jobs from search data repository.

Updated 3 months ago