Broadbean Developers

CV Databases
FAQ

Stream integration for Job Boards & CV/Résumé database

Stream is a federated search tool which allows multiple sources (Channels) to be searched from a single interface. More information on the product can be found here.

Introduction

These notes are intended to provide technical information to operators of CV/Résumé databases (including those operated by Job Boards) on how to join the Stream network.

For new site builds, this document should be taken into consideration during the planning phase.

In order to join the Stream network, you are required to provide us access to a 'Search API' to which we will send XML requests and receive XML responses.

Prerequisites

A detailed understanding of the architecture of your CV/Résumé database.
An understanding of the concepts of processing XML over HTTP.
Basic understanding of the Stream product.

Checklist

What we need from you:

An API to access your candidate database
API docs including:
url to access API
which fields are mandatory
valid options for each field
Test credentials
Contact for support queries

We will provide:

Stream test account
Stream demo if desired
Profile on Broadbean website

Process

There are 2 aspects to Stream:

Searching.
Candidate retrieval.

Stream will send a search request to the API provided by you, to us. In response to this request, your API will extract the search criteria, and perform a search on the candidate database (exactly the same way it would as via an HTML form submission). The results from this search are then passed back to us as a response (as XML). We then present the results to the user for review (in the same way you would present them as search results if the user was using your site directly). The user will choose candidates from these results who they wish to take a closer look at; at this point we will send you a secondary request specifying the candidate. Your response to this request should be to send us the complete candidate profile plus any documents you store for that candidate (usually a Word version of their CV/Résumé).

API requirements

The following requirements should be considered when designing the API:

The API must accept one search/candidate request per transaction.
The API must respond in real-time; connections with no data flow will be terminated and marked as failed after 20 seconds.
The API must be multi-threaded as we will make concurrent connections.
Each result must have a system whereby the candidate is uniquely identifiable (usually via email address or candidate ID in your database).
In the event of a failure/error being encountered, the API must send a meaningful response. Examples include "Username/Password not recognised", "insufficient credit", "Database unable to serve request" etc. Please do not return error codes as these are meaningless to users.
The API must be capable of accepting values for a number of results and an offset (for example we may request 50 results with an offset of zero giving us the first 50 results. We may then add an offset of 50, re-run the request, and we would expect to receive the second 50 results in response).
All content must be valid XML and declared and encoded as UTF-8.

Hints & Tips for a good interface

include the candidate email in the search results
if pay per view, include the candidate email in the profile or with the CV
provide access to the word CV rather than an XML or text CV
the API should be able to mirror searching directly as much as possible
include as much candidate detail as possible in the search result and profile
provide an example search response and request
use an XML library to create XML

Example Search request

<?xml version="1.0" encoding="UTF-8"?>
<CV_Search_Query>
    <Account>
        <Username></Username>
        <Password></Password>
    </Account>
    <Search_Query>
        <Keywords><!-- boolean search //--></Keywords>
        <Location></Location>
        <Radius></Radius>
        <Contract_Type><!-- Permanent/Contract //--></Contract_Type>
        <Salary_Cur></Salary_Cur>
        <Salary_Min></Salary_Min>
        <Salary_Max></Salary_Max>
        <Salary_Rate></Salary_Rate>
        <Updated_within>90<!-- days //--></Updated_within>
        <Limit_Results_to><!-- number of results to return //--></Limit_Results_to>
        <Results_offset>25</Results_offset>
    </Search_Query>
</CV_Search_Query>

Example Search response

<?xml version="1.0" encoding="UTF-8"?>
<CV_Search_Query>
    <Search_Response>
        <Results>
            <Result>
                <Record_Id>12345</Record_Id>
                <Name></Name>
                <Email></Email>
                <Snippet></Snippet>
                <Last_contacted><!-- e.g. 10th August 2008 by Joe Bloggs //--></Last_contacted>
            </Result>
            <Result>...</Result>
            <Result>...</Result>
            <Result>...</Result>
            <Result>...</Result>
        </Results>
    </Search_Response>
</CV_Search_Query>

Example candidate retrieval request

<?xml version="1.0" encoding="UTF-8"?>
<CV_Search_Query>
    <Account>
        <Username></Username>
        <Password></Password>
    </Account>
    <Candidate_CV_Query>
        <Record_Id>1234</Record_Id>
    </Candidate_CV_Query>
</CV_Search_Query>

Example candidate retrieval response

<?xml version="1.0" encoding="UTF-8"?>
<CV_Search_Query>
    <Candidate_CV_Response>
        <File transform="base64" filename="Efinancial-1234.doc" content-type="application/msword">
            <!-- base64 encoded file //-->
        </File>
    </Candidate_CV_Response>
</CV_Search_Query>