Developers

Add video interviewing to your platform

All you need to know is right here



Starting with The Needle API's


Welcome to The Needle's API documentation. All our public APIs are described on these pages, including all the information you require to begin integrating the APIs into your own system for testing and final deployment. Please take your time to read through our documentation, and if you have any suggestions, comments or questions, get in touch with us. We'll get back to you as soon as we can.


Get your API key


To begin developing and testing your integration, you first need a test API Key. This API key is required to enable any dialogue with our servers. Contact us on this page or call us on +44 (0)345 868 0100 to discuss access to the APIs. We will generate your key within a couple of days. You will then be able to begin tests on our dedicated test server https://apitest.theneedleonline.com .

Once you have completed your tests, we will then exchange the test key with a production API key. You can then use the full functionality of The Needle's video interviewing system on https://app.theneedleonline.com.

Document Version History


The Needle is constantly improving and extending the APIs presented in this document. The Table below provides a brief history of all updates, the features added or modified, and the 'go live' dates of each version. If you have any comments, suggestions or comments, please contact us here.


API VERSION GO LIVE DATE CHANGES AND UPDATES
1.0 2016-02-18 First release of The Needle JSON APIs

Account Management


To access and use The Needle's video interviewing platform, you will need a user account. This account can be individual, or can be shared by multiple users. Note that if you share an account, all users with access to that account will be able to view all jobs, candidates, video interviews and messages associated with that account. This API allows you to create a user account, or modify an existing account.


API Method


https://apitest.theneedleonline.com/api_account/save


This API is a PUT API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
account_key Text (max length 64) Unique ID for this account. If this value is set, the account associated with this key is updated. If not set, a new account is created.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES company_name Text (max length 255) The name of the company offering the advertised role.
YES contact_name Text (max length 255) The name of the hiring manager.
YES contact_email Text (max length 255) The e-mail address of the hiring manager.
needle_email Tinyint (1) If The Needle e-mail messaging system is to be used, then this value should be = 1. If the system integrated should use it's own or an alternative messaging system, this value should be empty or = 0. The default value is = 0.
time_zone Text (max length 255) The label of the timezone where the hiring manager is located. The complete list is given in the table at the end of this section. Where no value is entered, this will default to "London, Dublin, Lisbon".
company_logo Text (max length 255) The URL to the account holder's company logo, which will be displayed in the page header of all candidate facing pages. This should be in PNG or JPEG format, maximum size W:200, H:100 pixels. If no URL is present, The Needle logo will be used as default.
video_poster Text (max length 255) The URL to the image to be used as the video poster for all account holder related videos, in PNG format, 640x480 pixels. If no URL is available, The Needle logo will be used as default.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES account_key Text (max length 64) Alphanumeric string confirming the account key when a new user account is created


Timezone Table


The following labels give the timezone options accepted by the system.


TIMEZONE ID LABEL
2 Midway Island, Samoa
3 Hawaii
4 Alaska
5 Pacific Time (US & Canada)
6 Mountain Time (US & Canada)
7 Central Time (US & Canada)
8 Eastern Time (US & Canada)
9 Caracas
10 Atlantic Time (Canada)
11 Brazil, Buenos Aires
12 Mid-Atlantic
13 Azores, Cape Verde Islands
14 London, Dublin, Lisbon
15 Brussels, Copenhagen, Madrid
16 Kaliningrad, South Africa
17 Baghdad, Riyadh, Moscow
18 Abu Dhabi, Muscat, Baku
19 Kabul
20 Ekaterinburg, Islamabad
21 Bombay, Calcutta, Madras
22 Kathmandu
23 Almaty, Dhaka, Colombo
24 Yangon, Cocos Islands
25 Bangkok, Hanoi, Jakarta
26 Beijing, Singapore, Hong Kong
27 Tokyo, Seoul, Osaka
28 Adelaide, Darwin
29 Eastern Australia, Guam
30 Magadan, Solomon Islands
31 Auckland, Wellington, Fiji

Creating a job


Video interviews are typically related to a specific job. At The Needle, we put a lot of emphasis on informing and supporting the candidate during the interview process. The following API allows the recruiter to choose how much - or how little - information is shared with the candidate. Note that where a field is left blank, neither the field header nor missing data will be shown on the job description page - blanks will be simply ignored. Most of the job description will exist in other areas of the integrated systems, so there is no need to create this twice. In addition to a rich set of job description and requirements related fields, company branding and an embedded job or company related video are also supported with the API call. Finally this call includes the full Video Interview Structure, including up to 20 questions, maximum duration of each response, number or records allowed, etc..


API Method


https://apitest.theneedleonline.com/api_job/save


This API is a POST API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) The unique ID of the account being used.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
job_id Integer If this is set, this will update the existing job with the same ID. If this is not set, a new job will be created.
YES job_title Text (max length 255) The full job title of the open position to be interviewed for.
YES company_name Text (max length 255) The name of the company offering the position.
contact_name Text (max length 255) The full name of the hiring manager. If this is empty, the name of the account holder will be used as default.
contact_email Text (max length 255) The e-mail address of the hiring manager. If this is empty, the e-mail address of the account holder will be used as default.
YES job_reference Text (max length 255) The code that the hiring manager or future employer has assigned to identify this job.
YES location Text (max length 255) Details of where the job will be based, e.g. town, county, country.
YES closing date Text (max length 16) Closing date for all job applications, in the format YYYY-MM-DD.
contract_type Text (max length 64) For example, one of the following - Permanent / Contract / Part time.
benefits Text any length Details of any job specific benefits over and above main salary.
YES job_description Text (any length) This mandatory field is a detailed job description, which can provide the candidate with a good overview of the job applied for.
essential_skills Text (any length) The essential skills which a suitable candidate must possess.
desirable_skills Text (any length) Additional skills which a suitable candidate should possess.
YES company_about Text (any length) Details of the company which will be the future employer. This will be posted in the 'About the Company' area of the job description page the candidate sees.
company_logo Text (max length 255) This is a URL to the employer's logo. This will be posted in the 'About the Company' area of the job description page the candidate sees.
company_video Text (max length 255) This is a YouTube URL to a video about either the job or the employer. This will be posted in the 'About the Company' area of the job description page the candidate sees.
interview_allow_preparation Integer If the candidate is allowed to see the video interview questions in advance and create their own Speaker Notes, then this should be set to 1. If the auto-record option is used, this should be empty or 0. Where no value is set, the default will be 0.
interview_preview_duration Text (max length 5) This is the 'reading and thinking' time each candidate has before the response recording starts automatically. This should be in the format MM:SS, and be a value between 00:05 and 05:00. Where no value is set, a default of 00:15 will be used. Note that if interview_allow_preparation = 1, this parameter will be ignored.
A minimum of ONE and a maximum of TWENTY (20) questions are possible and should be included here in the order they are to be presented in the video interview. Note that all three parameters should be included for each question, or the default values will apply.
YES interview_question_text Text (max length 255) Text of the question
interview_question_timelimit Text (max length 5) Maximum duration allowed for the candidate to respond to the question, in the format MM:SS, and between the values of 00:30 and 10:00. Where no value is set, a default value of 01:00 is used.
interview_question_rerecords Integer The maximum number of chances to record each response, either 0, 1, 2 or 3. Where no value is set, a default value of 0 is used.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES job_id Integer This will be the original job_id value if used when posting, or a new job_id if a new job is created.

Inviting Candidates


Once a job and a video interview structure has been created, you can invite candidates to complete a video interview using this API.


API Method


https://apitest.theneedleonline.com/api_job/post_invitation


This API is a POST API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) The unique ID of the account being used.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES job_id Integer The unique ID of the job related to the video interview.
YES candidate_name Text (max length 255) The name of the candidate to be invited.
YES candidate_email Text (max length 255) The e-mail address of the candidate to be invited.
YES expiry_date Text (max length 255) This is the date and time that the invitation expires, in the format YYYY-MM-DD hh:mm.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES target_id integer The unique identifier for this candidate
YES target_hash Text (max length 64) The unique hash value associated with the candidate for this job. Note that if the same candidate applies for different jobs, a different unique hash value will be created for each job.
YES target_url Text (max length 255) The URL sent to the candidate to complete the video interview, format is typically https://apitest.theneedleonline.com/jobs/view_invitation/[target_hash].

Accessing the completed Video Interview


Once the candidate has completed the video interview, it is available for presentation within your application. This API accesses the video URL.


When the video interview is available, The Needle’s server will call a URL that the partner has previously provided. For example, the company Recruitco Ltd. could have there servers at the URL https://www.recruitco.com. The URL will refer to a page implemented on the partner's server, e.g. /interview_response.php, which would then store the values returned against the candidate's interview.


Call back URL


https://www.recruitco.com/interview_response.php?hash=[target_hash]&videohash=[videohash]&photo=[photo]


The partner's CALL BACK URL will be called with the candidate details and the video has details, which will allow the partner to access the completed video interview.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES target_hash Text (max length 64) The unique hash value associated with the candidate for this job. Note that if the same candidate applies for different jobs, a different unique hash value will be created for each job.
YES videohash Text (max length 64) The unique hash associated with the video interview.
photo Text (max length 255) The URL of the photo taken by the candidate e.g. https://apitest.theneedleonline.com/images/20151223142345.jpg. If the candidate did not take a photo, this parameter will be empty.


Requesting an interview Status


If for whatever reason the integrating platform is unable to receive callbacks when a candidate has completed their interview, there is an alternative method for retrieving the information such as the interview hash, video hash and URL for the candidates photograph (if taken). This API calls The Needle to check the status of each candidate or target. If a video has been completed, then the necessary information will be returned allowing a video URL to be built. If the interview has not yet been completed, these return fields will be empty.


API Method


https://apitest.theneedleonline.com/api_target/getstatus/


This API is a POST API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) The unique ID for the account being used.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES target_id Integer This is the target_id associated with the candidate, whose video interview status is being requested.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES interview_outstanding Tinyint (1) If the candidate has completed the video interview, the value will be = 0, otherwise the value will be = 1.
target_hash Text (max length 64) The unique hash value associated with the candidate for this job. Note that if the same candidate applies for different jobs, a different unique hash value will be created for each job.
video_hash Text (max length 64) The unique hash associated with the video interview.
photo Text (max length 255) The URL of the photo taken by the candidate e.g. https://apitest.theneedleonline.com/images/20151223142345.jpg. If the candidate did not take a photo, this parameter will be empty.
api_view Text (max length 255) The complete URL of the video interview player which can be embedded in your application.


Presenting the completed Video Interview


The video hash can be used to assemble a URL to access the finished interview, with the typical format https://apitest.theneedleonline.com/interview_responses/api_view/[videohash].


This URL is typically embedded as an iframe in the partner's application, or opens in a new browser tab. Dimensions of the iframe are optimised to 640 x 630, which presents the video player plus the question select buttons.

Creating a Short List


Once the candidate video interviews have been reviewed, you can invite hiring managers or other decision makers to review and comment on selected candidates using the Short List APIs.


https://apitest.theneedleonline.com/api_shortlist/save


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) The unique ID for the account being used.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
shortlist_id Text (max length 64) If this value is set, the shortlist associated with this value is updated. If not set, a new shortlist_id is created.
YES job_id Integer The job ID of the job the candidates have completed the video interview for.
A minimum of ONE candidate must be included in the Short List. Multiple candidates can be added to the Short List when it is being created.
YES target_id Text (max length 255) The unique ID of the candidate to be included in the Short List.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES shortlist_id Text (max length 64) The unique ID of the Short List, if a shortlist_id is entered in the call, the same value will be returned. If no value is entered, a new shortlist_id is created and returned here.
YES shortlist_hash Text (max length 64) The unique hash value for the Short List, as used in the final URL.
YES shortlist_URL Text (max length 255) The base URL sent to the invitees to view the Short List, format is typically https://apitest.theneedleonline.com/sv/[shortlist_hash] (NOTE. See below for construction of the final URLs).


Inviting to a Short List


Once the Short List has been created, you can invite hiring managers or other decision makers to review and comment on selected candidates using the Short List APIs.

API Method


https://apitest.theneedleonline.com/api_shortlist/post


This API is a POST API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) The unique ID for the account being used.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
A minimum of ONE invitee must be included here, and multiple invitees can be added. Note that all three parameters must be included for each invitee. The shortlist_expiry period can be set individually for each invitee.
YES shortlist_id Text (max length 64) The unique ID of the Short List to which people are being invited to.
YES invitee_name Text (max length 255) The name of the person invited to review the Short List.
YES invitee_email Text (max length 255) The e-mail address of the person invited to review the Short List.
shortlist_expiry Integer Defines the number of days which the invitees can access the Short List for review after the invitation has been sent. If no value is entered, a default value of three (3) days will be applied.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES shortlist_id Text (max length 64) The unique ID of the Short List, this is the same value as entered in the call.
A minimum of ONE invitee will be included here, where multiple invitees were invited to the Short List, a unique ID for each invitee will be returned.
YES invitee_id Integer The unique ID of the Short List invitee. This must be added to the base Short List URL to create the unique URL for each invitee.
YES invitee_name Text (max length 255) The name of the person invited to review the Short List.
YES invitee_email Text (max length 255) The e-mail address of the person invited to review the Short List.


Constructing the unique Short List URL for each invitee


The invitee_id must be added individually to the base URL sent to each invitee to view the Short List, the final format is typically https://apitest.theneedleonline.com/sv/[shortlist_hash]/[invitee_id]. This is necessary to differentiate the comments and ratings from each Short List invitee.

Get Comments and Ratings


Short List invitees can review the video interview, then add their own comments and a rating between 1-10. These comments and ratings can be requested from The Needle using this API.


API Method


https://apitest.theneedleonline.com/api_shortlist/getstatus


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) The unique ID of the account being used.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES shortlist_id Text (max length 64) The unique ID of the Short List from which comments are to be retrieved.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES shortlist_id Text (max length 64) The unique ID of the Short List, this is the same value as entered in the call.
YES target_id Integer The unique ID of the candidate in the Short List
YES invitee_id Integer The unique ID of the Short List invitee.
invitee_comment Text (any length) Comments made by the invitee about the candidate. This field will be empty if the invitee has not made any comments.
invitee_rating Integer Rating of candidate between 1 and 10, provided by the invitee. This field will be empty if the invitee has not made any rating.


Multiple Comments and Ratings


Note that multiple invitees will add their comments and ratings at different times. It is therefore recommended that this API is used roughly every 60 minutes, and the data updated in the partner's system.

Admin and Reporting


Everybody has KPIs! The Needle offers a rich set of reporting tools to track jobs, invitations, completed interviews - even which devices were used to complete the video interviews. Use these APIs to get all the information you need to check overall status and compile your management reports.


Total jobs posted to date


This API call returns the total number of jobs posted for the selected user account throughout the lifetime of the account to the present day.


API Method


https://apitest.theneedleonline.com/api_account/jobs_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of jobs posted, from the account start date till the current day.


Total jobs posted in a selected period


This API call returns the total number of jobs posted for the selected user account between the defined start and end dates.


API Method


https://apitest.theneedleonline.com/api_account/jobs_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES start_date Date Start date from when jobs posted should be calculated, format YYYY-MM-DD.
YES end_date Date End date till when jobs posted should be calculated, format YYYY-MM-DD.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of jobs posted, between the selected start date and end date.


Total video invitations sent to date


This API call returns the total video invitations sent from the selected user account between the start of the account and the current day.


API Method


https://apitest.theneedleonline.com/api_account/invitations_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of invitations sent, from the account start date till the current day.


Total video invitations for a selected job


This API call returns the total video invitations sent from the selected user account for a specific job.


API Method


https://apitest.theneedleonline.com/api_account/invitations_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES job_id Integer The unique job ID selected.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of invitations sent for a specific job.


Total video invitations in a selected period


This API call returns the total number of invitations sent for the selected user account between the defined start and end dates.


API Method


https://apitest.theneedleonline.com/api_account/invitations_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES start_date Date Start date from when jobs posted should be calculated, format YYYY-MM-DD.
YES end_date Date End date till when jobs posted should be calculated, format YYYY-MM-DD.

Response Parameters

MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of invitations sent, between the selected start date and end date.


Total video interviews completed to date


This API call returns the total number of video interviews completed for the selected user account between the start of the account and the current day.


API Method


https://apitest.theneedleonline.com/api_account/interviews_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of completed video interviews, from the account start date till the current day.


Total video interviews completed for a selected job


This API call returns the total video interviews completed sent from the selected user account for a specific job.


API Method


https://apitest.theneedleonline.com/api_account/interviews_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES job_id Integer The unique job ID selected.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of completed video interviews for the selected job.


Total completed video interviews in a selected period


This API call returns the total number of completed video interviews for the selected user account between the defined start and end dates.


API Method


https://apitest.theneedleonline.com/api_account/interviews_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES start_date Date Start date from when jobs posted should be calculated, format YYYY-MM-DD.
YES end_date Date End date till when jobs posted should be calculated, format YYYY-MM-DD.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES count Integer Total number of completed video interviews for the account selected between the start date and the end date.


Percentage of video interviews completed to date


This API call returns ratio in % of video interviews completed to invitations sent for the selected user account between the start of the account and the curent day.


API Method


https://apitest.theneedleonline.com/api_account/interviews_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES percentage Integer Ratio of completed video interviews to invitations sent, from the account start date till the current day.


Percentage of video interviews completed for a selected job


This API call returns ratio in % of video interviews completed to invitations sent for the selected user account for a specific job.


API Method


https://apitest.theneedleonline.com/api_account/interviews_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES job_id Integer The unique job ID selected.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES percentage Integer Ratio of completed video interviews to invitations sent, for the selected job.


Percentage of video interviews completed in a selected period


This API call returns ratio in % of video interviews completed to invitations sent for the selected user account for the selected user account between the defined start and end dates.


API Method


https://apitest.theneedleonline.com/api_account/interviews_report


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES start_date Date Start date from when jobs posted should be calculated, format YYYY-MM-DD.
YES end_date Date End date till when jobs posted should be calculated, format YYYY-MM-DD.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES percentage Integer Ratio of completed video interviews to invitations sent for the account selected between the start date and the end date.


Devices used to date


This API call returns details of the devices used to complete the video interviews (Laptop, Apple App or Android App) for the selected user account between the start of the account and the curent day.


API Method


https://apitest.theneedleonline.com/api_account/interview_devices


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES laptop Integer Number of video interviews completed on a laptop for the selected account, from the account start date to the current day.
YES iOS Integer Number of video interviews completed on an Apple device for the selected account, from the account start date to the current day.
YES Android Integer Number of video interviews completed on an Android device for the selected account, from the account start date to the current day.


Devices used for a selected job


This API call returns details of the devices used to complete the video interviews (Laptop, Apple App or Android App) for the selected user account for a specific job.


API Method


https://apitest.theneedleonline.com/api_account/interview_devices


This API is a GET API.


Query Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES api_key Text (max length 64) Alphanumeric string identifying client connecting to TNO server
YES account_key Text (max length 64) Unique user account ID.
YES api_version Text (max length 16) The version of the API Framework used, the current version is = 3 for JSON APIs.
YES job_id Integer The unique job ID selected.


Response Parameters


MANDATORY FIELD NAME DATA TYPE COMMENTS
YES laptop Integer Number of video interviews completed on a laptop for the selected job.
YES iOS Integer Number of video interviews completed on an Apple device for the selected job.
YES Android Integer Number of video interviews completed on an Android device for the selected job.

The Needle API's - Examples


The APIs described in the previous tabs are all described again using coding examples. Please review the documentation and examples, and if you have any suggestions, comments or questions, get in touch with us. We'll get back to you as soon as we can.


The following examples are in cURL format. We also recommend using the Google Chrome Postman App for testing your implementation.


Account Management


$ curl -X POST -H "Content-Type: application/json" -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"" }, "needleaccountdata" : { "company_name":"the needle online ", "contact_name":"test contact", "contact_email":"test_email3@gmail.com", "time_zone":"London, Dublin, Lisbon" } }' 'https://apitest.theneedleonline.com/api_account/save'

As no account key was used in this example, the following account key is created and received as a response:

302fa8943103f5e78519e5f5b61ca079


Job Management


curl -X POST -H "Content-Type: application/json" -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"302fa8943103f5e78519e5f5b61ca079" }, "needlejobdata": { "job_title": "Test Job", "company_name": "Test Company", "company_about": "We are recruiters", "company_logo": "http://www.THIRDPARTY.com/companyxlogo.jpg", "video_poster": "https:// www.THIRDPARTY.com/companyxposter.png", "contact_name": "Mr HR Manager", "contact_email": "hrmanager@testco.com", "job_reference": "TJ001", "location": "London", "closing_date": "2016-03-31", "contract_type": "Permanent", "job_description": "This is a test job", "essential_skills": "Driving Licence", "company_video": "https://www.youtube.com/watch?v=RWfCThz-SWQ", "interview_allow_preparation": "0", "interview_preview_duration": "00:30", "interview_questions": { "interview_question": [ { "interview_question_text": "What is question one?", "interview_question_timelimit": "00:30", "interview_question_rerecords": "0" }, { "interview_question_text": "What is question two?", "interview_question_timelimit": "01:00", "interview_question_rerecords": "1" } ] } } } ' 'https://apitest.theneedleonline.com/api_job/save'


As no job_id was entered, the following job_id is generated after execution of this API call:

job_id = 5051


Candidate Management


curl -X POST -H "Content-Type: application/json" -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"302fa8943103f5e78519e5f5b61ca079" }, "needleinvitationdata": { "job_id": "5051", "candidate_name": "John Smith", "candidate_email": "johnsmith277@gmail.com", "expiry_date": "2016-02-29" } }' 'https://apitest.theneedleonline.com/api_job/post_invitation'


After a successful job invitation is posted, the following target_id for this candidate is generated:

target_id = 8861


Candidate Interview Status


curl -X POST -H "Content-Type: application/json" -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"302fa8943103f5e78519e5f5b61ca079", "target_id":"8861" } }' 'https://apitest.theneedleonline.com/api_target/getstatus'


If the field 'interview_outstanding' = 1, the candidate has not completed the interview. If the field = 0, the target_hash, video_hash and photo URL (if available) will be returned.


Short List Management


curl -X POST -H "Content-Type: application/json" -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"302fa8943103f5e78519e5f5b61ca079" }, "needleshortlistcandidatesdata": { "job_id": "5051", "shortlist_candidates": { "target_id": [ "8861" ] } } }' 'https://apitest.theneedleonline.com/api_shortlist/save'


This API call has created a new Short List, including the candidate having the target_id = 8861, and has returned following shortlist_id:

shortlist_id = 516


curl -X POST -H "Content-Type: application/json" -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"302fa8943103f5e78519e5f5b61ca079" }, "needleshortlistinviteesdata": { "shortlist_id": "516", "invitee_name": "Jack Jones", "invitee_email": "jack@theneedleonline.com" } }' 'https://apitest.theneedleonline.com/api_shortlist/post'


Jack Jones has been invited to view the Short List with shortlist_id = 516, created in the previous example.


curl -X POST -H "Content-Type: application/json" -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"302fa8943103f5e78519e5f5b61ca079", "shortlist_id": "516" } }' 'https://apitest.theneedleonline.com/api_shortlist/getstatus'


This call can be made multiple times, each time the latest status on comments and ratings for each candidate in the Short List are returned. It is recommended that once per hour per shortlist is sufficient.


Reporting


The reporting APIs are all very similar, examples for each call are given below.


Total jobs posted to date


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d" } }' 'https://apitest.theneedleonline.com/api_account/jobs_report'


Total jobs posted in a specific period


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d", "start_date" : "2015-1-09", "end_date" : "2015-12-09" } }' 'https://apitest.theneedleonline.com/api_account/jobs_report'


Total video invitations sent to date


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d" } }' 'https://apitest.theneedleonline.com/api_account/invitations_report'


Total video invitations for a selected job


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d", "jobid" : "5034" } }' 'https://apitest.theneedleonline.com/api_account/invitations_report'


Total video invitations in a selected period


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d", "start_date" : "2015-1-13", "end_date" : "2015-12-09" } }' 'https://apitest.theneedleonline.com/api_account/invitations_report'


Total video interviews completed to date


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d" } }' 'https://apitest.theneedleonline.com/api_account/interviews_report'


Total video interviews completed for a selected job


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d", "jobid" :"5034" } }' 'https://apitest.theneedleonline.com/api_account/interviews_report'


Total completed video interviews in a selected period


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d", "start_date" : "2015-1-13", "end_date" : "2015-07-13" } }' 'https://apitest.theneedleonline.com/api_account/interviews_report'


Percentage of video interviews completed to date


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d" } }' 'https://apitest.theneedleonline.com/api_account/interviews_report_ratio'


Percentage of video interviews completed for a selected job


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d", "jobid" : "5034" } }' 'https://apitest.theneedleonline.com/api_account/interviews_report_ratio'


Percentage of video interviews completed in a selected period


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d", "start_date" : "2015-1-13", "end_date" : "2015-07-13" } }' 'https://apitest.theneedleonline.com/api_account/interviews_report_ratio'


Devices used to date


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d" } }' 'https://apitest.theneedleonline.com/api_account/interview_devices'


Devices used for a selected job


$ curl -H "Content-Type: application/json" -X POST -d '{ "needleaccountheader" : { "api_key": "37tf18456folshcb3476r934f83h4t86", "api_version":"3", "account_key":"f7ef85b75f21802df4a2a848e713897d" "jobid" : "5034" } }' 'https://apitest.theneedleonline.com/api_account/interview_devices'

Success Messages & Error Codes


Even the best developers sometime make mistakes, so The Needle has added a rich set of error codes to identify any missing or erroneous API calls made by your system. These should help you both in development and post deployment to catch any errors. Of course, when your post is successful, you'll also get an appropriate message, they are listed below also.


Success Messages


API CALL SUCCESS MESSAGE DESCRIPTION
Create Account Account is saved successfully! account_key value is returned.
Post Job Job is posted successfully! job_id value is returned.
Post Invitation Job invitation is posted successfully! "target_id", "target_url" and "target_hash" is returned.
Target Status Target status. "interview_outstanding", "target_hash", "video_hash", "photo" and "api_view" is returned.
Create Shortlist Shortlist is saved successfully! "shortlist_id","shortlist_url" and "shortlist_hash" is returned.
Post Shortlist Shortlist invitee(s) posted successfully! "invitee_id","invitee_name", "invitee_email", "shortlist_id", "shortlist_url" and "invitee_email" is returned.
Get Shortlist Status Shortlist status.. "targets" with "target" and "users" with their "comment" is returned.


Error Codes


ERROR CODE ERROR MESSAGE
2 Invalid API Key
3 Invalid account key
4 This API library is compatible to API Version 3. Please re-check!
5 The maximum stack depth has been exceeded.
Invalid or malformed JSON.
Control character error, possibly incorrectly encoded.
Syntax error, malformed JSON.
Malformed UTF-8 characters, possibly incorrectly encoded.
One or more recursive references in the value to be encoded.
One or more NAN or INF values in the value to be encoded.
A value of a type that cannot be encoded was given.
Unknown JSON error occured.
6 Invalid "fieldname" format
7 field value is required!
8 date value is invalid! Valid format is yyyy-mm-dd e.g. 2015-12-31
"fieldname", invalid time format!
"fieldname", hour value must be between 00 and 23
"fieldname", minutes value must be between 00 and 60
9 "field" value must be integer datatype! please check.
10 Invalid email format
11 Account email already exists. please re-check!
12 Timezone text is wrong, please check timezones listing in the API documentation!
13 Error saving record
14 Customer account not found
15 No questions
16 Invalid job ID
17 Account is not saved successfully. There is a database write error.
18 Target is not saved successfully. There is a database write error.
19 Invalid Target ID
20 Invalid candidate ID
21 Invalid shortlist ID
22 Target not found
23 Start date is invalid!
24 End date is invalid!
25 All three inputs (start_date, end_date and jobid) are not valid, please check API documentation for more detail!
26 Code not used
27 interview_question_text is required!
28 Account search failed!
29 Invalid shortlist_id, please check!
30 company_video value must be a youtube URL e.g. https://www.youtube.com/watch?v=RWfCThz-SWQ