OpenLabor API specification

General

The OpenLabor API is used by applications for sending job and training requests to Province of Rome (III Department). Following functionalities are provided by the API:
  • Listing of service request types and definitions of the additional attributes
  • Submitting service requests
  • Quering individual or multiple service requests and their descriptions and status
The issue reporting API is based on GeoReporting version 2, which is better known as Open311 specification. This interface is compliant with CitySDK specific enhancements to Open311

API Key

Applications submitting jobs/training offers or submitting comments will need API key. All other methods do not require API key.

Encoding and formats

UTF-8 is required everywhere. API supports both XML and JSON.

Language support

The language specification is forseen (the locale variable accept the format: en_US, it_IT)

API methods


Get service list


Provides a list of acceptable service request types and their associated service codes.

Request parameter


Parameter name Description Required Notes
locale Preferred language No At moment locale is not implemented

Response parameter


Parameter name Description Required Notes
service_code The unique identifier for the service request type. Yes The service_code is specified in the main URL path rather than an added query string parameter.
service_name The human readable name of the service request type Yes
description A brief description of the service request type. Yes
metadata Determines whether their are additional form fields for this service type.
  • true: This service request type requires additional metadata so the client will need to make a call to the Service Definition method.
  • false: No additional information is required and a call to the Service Definition method is not needed.
  • Yes At the moment metadata is always set to false.
    type realtime: The service request ID will be returned immediately after the service request is submitted. Yes At the moment, type is always set to realtime.
    keywords A comma separated list of tags or keywords to help users identify the request type. This can provide synonyms of the service_name and group. Yes
    group A category to group this service type within. This provides a way to group several service request types under one category such as "sanitation" Yes

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

    http://devopenlabor.lynxlab.com/api/v1/services.json

    Example response:

        
        service: [
    {
    service_code: "001",
    service_name:"search_jobs",
    description: "jobs find",
    metadata: "true",
    type: "realtime",
    keywords: "retrives single job, retrives list of jobs ",
    group: "training and job"
    },
    {
    service_code:"002",
    service_name:"job_reports",
    description: "reports jobs",
    metadata:"true",
    type: "realtime",
    keywords: {},
    group: "training and job"
    },
    

    Get service definition


    Define attributes associated with a service code.

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes The service_code is specified in the main URL path rather than an added query string parameter.

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

    http://devopenlabor.lynxlab.com/api/v1/services/002.json

    Example response:

    {
    service_code: "002",
    http_method: "POST",
    attributes: {
    attribute: [
    {
    variable: "true",
    code: "api_key",
    datatype: "string",
    required: "true",
    datatype_description: { },
    order: "1",
    description: "api key"
    },
    {
    variable: "true",
    code: "jurisdiction_id ",
    datatype: "string",
    required: "false",
    datatype_description: "This is only required if the endpoint serves multiple jurisdictions",
    order: "1",
    description: "jurisdiction id"
    },
    {
    variable: "true",
    code: "locale",
    datatype: "string",
    required: "false",
    datatype_description: "Choose of preferred language",
    order: "1",
    description: "language in format en_US, it_IT,"
    },
    

    Get JOBS search


    Provides a list of jobs offers.

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes 001
    jurisdiction_id jurisdiction_id is only required if the endpoint serves multiple jurisdictions No
    locale Preferred language No language in format en_US, it_IT
    keywords keywords separated by comas No keywords to find a job
    city City in which looking for job No
    qualification educational qualification of the candidate No

    Response parameter


    Parameter name Description Required Notes
    idJobOffers unique identifier of a job offers Yes
    idJobOriginal original unique identifier of a job offers Yes
    jobExpiration deadline (in unixtime) to submit the application Yes
    workersRequired number of works required Yes
    professionalProfile professional profile required Yes
    professionalProfile professional profile required Yes
    positionCode National Professional Code according with international professional code (ISCO-08) Yes get the value from national professional code system (ex: in Italy from ISTAT: http://cp2011.istat.it/)
    position position Yes
    qualificationRequired educational qualification of the candidate Yes
    descriptionQualificationRequired description of competences of educational qualification of the candidate Yes
    professionalTrainingRequired professional Training Required Yes
    cityCompany City in which is based the company hiring Yes
    idCPI identifying employment center Yes
    experienceRequired Experience required by the company Yes
    durationExperience how many year of experience the company requires Yes
    minAge minimum age required Yes
    maxAge maximum age required Yes
    remuneration remuneration offered by the company Yes
    rewards rewards offered by the company Yes
    reservedForDisabled whether the job is reserved to disable people Yes
    favoredCategoryRequests to which kind of disabilities are reserved job (only if reserved for disabled is true) Yes
    ownVehicle whether the hiring candidate has to have a own vehicle Yes
    notes notes Yes
    linkMoreInfo URL to more info about job offer Yes
    dateInsert insertion date Yes
    sourceJob email address of the person who report the job offer or his/her id Yes
    j_latitude Latitude using the (WGS84) projection. Yes
    j_longitude Longitude using the (WGS84) projection. Yes
    contractType Type of contract Yes
    j_address Human entered address or location Yes
    zipCode Human entered zip code (CAP in Italy) Yes
    nation The nation in which is based the company hiring Yes
    media_url URL to media Yes
    locale language Yes language in format en_US, it_IT
    sourceJobName first name of the person who report the job offer or his/her id Yes
    sourceJobSurname last name of the person who report the job offer or his/her id Yes
    published whether job offer is published Yes
    j_idNode id of relative node Yes
    CPICod code of employment center Yes
    nameCPI name of employment center Yes
    address address of employment center Yes
    CAP zip code of employment center Yes
    city city of employment center Yes
    CPIzone zone of employment center Yes
    phone phone of employment center Yes
    fax fax of employment center Yes
    email email of employment center Yes
    latitude latitude of employment center Yes
    longitude longitude of employment center Yes
    source source of employment center Yes

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

    http://devopenlabor.lynxlab.com/api/v1/requests.json?service_code=001

    Example response:

        
    {
    idJobOffers: "25",
    idJobOriginal: "3481",
    jobExpiration: "1392850800",
    workersRequired: "1",
    professionalProfile: "AIUTO COMMESSO DI LIBRERIA",
    positionCode: "5.1.2.2.0.5",
    position: "AIUTO COMMESSO",
    qualificationRequired: "ISTITUTO PROFESSIONALE (SECONDO CICLO) - SCUOLA MAGISTRALE (5 ANNI) - ISTITUTO TECNICO - ISTITUTO MAGISTRALE (4 E 5 ANNI) - LICEI SCIENTIFICO, CLASSICO, LINGUISTICO - ISTITUTO D'ARTE (SECONDO CICLO) - LICEO ARTISTICO (4 E 5 ANNI) - ISTITUTO SUPERIORE",
    descriptionQualificationRequired: "DIPLOMA DI ISTRUZIONE SECONDARIA SUPERIORE CHE PERMETTE L'ACCESSO ALL'UNIVERSITA'",
    professionalTrainingRequired: "",
    cityCompany: "VALMONTONE",
    idCPI: "17",
    experienceRequired: "DISCRETA CONOSCENZA DEL PRODOTTO LIBRO",
    durationExperience: "0",
    minAge: "0",
    maxAge: "0",
    remuneration: "0",
    rewards: "-",
    reservedForDisabled: "SI",
    favoredCategoryRequests: "ARTICOLO 1 LEGGE 68/99",
    ownVehicle: "-",
    notes: "CONTRATTO DI LAVORO PART-TIME CON TURNI DIURNI E FESTIVI DALLE ORE 10.00 ALLE 20.30. INDISPENSABILE: DIPLOMA DI SCUOLA MEDIA SUPERIORE, BUONA CONOSCENZA OFFICE , DISCRETA CONOSCENZA DEL PRODOTTO LIBRO, PRESENTARE CURRICULUM VITAE AL MOMENTO DELL'AUTOCANDIDATURA. PREFERIBILE: ETA' 21-40 ANNI, BUONA CONOSCENZA LINGUA INGLESE, ESPERIENZA DI VENDITA AL PUBBLICO, PATENTE DI GUIDA CAT. A.",
    linkMoreInfo: "http://co.provincia.roma.it/ido/Offerta.aspx?idOfferta=3481&Pubblica=1",
    dateInsert: "1391794370",
    sourceJob: "http://co.provincia.roma.it/ido/XmlOpenData/Preselezioni.xml",
    j_latitude: "",
    j_longitude: "",
    contractType: "",
    j_address: "",
    zipCode: "",
    nation: "",
    media_url: "",
    locale: "",
    sourceJobName: "",
    sourceJobSurname: "",
    published: "0",
    j_idNode: "1_25",
    CPICod: "COLLEFERRO",
    nameCPI: "Centro per l'Impiego Colleferro",
    address: "Via Carpinetana Sud, 144 ",
    CAP: "00034",
    city: "Colleferro",
    CPIzone: "Artena, Carpineto Romano, Colleferro, Gavignano, Gorga, Labico, Montelanico, Segni, Valmontone",
    phone: "06.97235000 ",
    fax: "06.97236327",
    email: "impiego.colleferro@provincia.roma.it",
    latitude: "41.723812",
    longitude: "13.011224",
    source: ""
    },
    

    Post reporting job service


    This method is used for sending a job report.

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes 002
    api_key The unique identifier for the service request type. Yes api_key
    jurisdiction_id jurisdiction_id is only required if the endpoint serves multiple jurisdictions No
    locale Preferred language No language in format en_US, it_IT
    professionalProfile professional profile required Yes
    positionCode National Professional Code according with international professional code (ISCO-08) Yes National Professional Code according with international professional code (ISCO-08)
    position position Yes
    contractType Type of contract Yes
    workersRequired number of works required Yes
    jobExpiration deadline (in unixtime) to submit the application Yes
    descriptionQualificationRequired description of competences of educational qualification of the candidate No
    professionalTrainingRequired professional Training Required No
    address Human entered address or location No
    zipCode Human entered zip code (CAP in Italy) No
    cityCompany City in which is based the company hiring No
    nation The nation in which is based the company hiring No
    experienceRequired Experience required by the company No
    durationExperience how many year of experience the company requires No
    minAge minimum age required No
    maxAge maximum age required No
    remuneration remuneration offered by the company No
    rewards rewards offered by the company No
    reservedForDisabled whether the job is reserved to disable people No
    favoredCategoryRequests to which kind of disabilities are reserved job (only if reserved for disabled is true) No
    ownVehicle whether the hiring candidate has to have a own vehicle No
    notes notes No
    linkMoreInfo URL to more info about job offer No
    j_latitude Latitude using the (WGS84) projection. No
    j_longitude Longitude using the (WGS84) projection. No
    sourceJob email address of the person who report the job offer or his/her id Yes
    sourceJobName first name of the person who report the job offer or his/her id Yes
    sourceJobSurname last name of the person who report the job offer or his/her id Yes
    media_url URL to media No
    published whether job offer is published No

    Response parameter


    Parameter name Description Required Notes
    AddedJobId job id returned Yes

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

        
    POST /api/v1/requests.json
    Host: openlabor.lynxlab.com
    Content-Type: application/x-www-form-urlencoded; charset=utf-8
    
    service_code=002
    

    Example response:

        
    {
    AddedJobId: "62"
    }
    

    Post comment job service


    This method is used for sending comments of jobs offers.

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes 003
    api_key The unique identifier for the service request type. Yes api_key
    jurisdiction_id jurisdiction_id is only required if the endpoint serves multiple jurisdictions Yes
    locale Preferred language No language in format en_US, it_IT
    job_id Id of the job to be commented Yes
    comment_text IThe text of the comment Yes
    c_latitude Latitude using the (WGS84) projection. No
    c_longitude Longitude using the (WGS84) projection. No
    c_user email address of the person who comment the job offer or his/her id Yes
    c_user_firstname first name of the person who comment the job offer No
    c_user_surname last name of the person who comment the job offer No
    c_published whether the comment is published No

    Response parameter


    Parameter name Description Required Notes
    AddedCommentToJobId comment id returned Yes

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

        
    POST /api/v1/requests.json
    Host: penlabor.lynxlab.com
    Content-Type: application/x-www-form-urlencoded; charset=utf-8
    
    service_code=003
    

    Example response:

     
    {
    AddedCommentToJobId: "1_71"
    }
    

    Get opportunities search service


    Get details of the training opportunities

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes 005
    jurisdiction_id jurisdiction_id is only required if the endpoint serves multiple jurisdictions No
    locale Preferred language No language in format en_US, it_IT
    keywords A comma separated list of tags or keywords to help users identify the request type. This can provide synonyms of the service_name and group. No keywords to find a course/training
    city City in which looking for trainings No
    qualification educational qualification of the candidate No

    Response parameter


    Parameter name Description Required Notes
    idTraining unique identifier of a training Yes
    IdTrainingOriginal original unique identifier of a training Yes
    nameTraining name of a training Yes
    trainingCode code of a training Yes
    company the name of the company delivering the training Yes
    trainingAddress address where the course takes place Yes
    zipCode Human entered zip code (CAP in Italy) Yes
    city City where the course takes place No
    phone contact of the company that delivers the training (email, phone, web site) Yes
    durationHours Duration of the training in hours Yes
    trainingType training type Yes
    t_userType the user type to whom the course is aimed Yes
    t_qualificationRequired educational qualification of the candidate Yes
    t_longitude longitude using the (WGS84) projection. Yes
    t_latitude latitude using the (WGS84) projection Yes
    t_dateInsert insertion date of the training Yes
    hash hash code of the training Yes
    t_source email address of the person or his/her id Yes
    t_nation city where the course takes place Yes
    t_minAge minimum age required for the training Yes
    t_maxAge maximum age required for the training Yes
    t_price remuneration offered by the company Yes
    t_reservedForDisabled whether the training is reserved to disable people Yes
    t_favoredCategoryRequests to which kind of disabilities are reserved training Yes only if reserved for disabled is true
    t_notes notes Yes
    t_expiration deadline (in unixtime) to submit the training Yes
    t_linkMoreInfo URL to more info about training offer Yes
    t_media_url URL to media Yes
    locale Preferred language No language in format en_US, it_IT
    sourceTrainingName first name of the person who report the training offer or his/her id Yes
    sourceTrainingSurname last name of the person who report the training offer or his/her id Yes
    t_published whether training offer is published Yes
    t_idNode node of the training Yes

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

    http://devopenlabor.lynxlab.com/api/v1/requests.json?service_code=005

    Example response:

    CAP: "00174",
    city: "ROMA",
    phone: "06/7101749",
    durationHours: "1800",
    trainingType: "QUALIFICA",
    t_userType: null,
    t_qualificationRequired: null,
    t_longitude: null,
    t_latitude: null,
    t_dateInsert: "1392669989",
    hash: "",
    t_source: "",
    t_nation: null,
    t_minAge: null,
    t_maxAge: null,
    t_price: null,
    t_reservedForDisabled: "",
    t_favoredCategoryRequests: null,
    t_notes: null,
    t_expiration: "0",
    t_linkMoreInfo: null,
    t_media_url: "",
    t_locale: "",
    sourceTrainingName: "",
    sourceTrainingSurname: "",
    t_published: "0",
    t_idNode: "2_1"
    },
    

    retrieve comments to job service


    This method is used for gettin comments of jobs offers.

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes 004
    api_key The unique identifier for the service request type. No api_key
    jurisdiction_id jurisdiction_id is only required if the endpoint serves multiple jurisdictions No
    locale Preferred language No language in format en_US, it_IT
    job_id Id of the job commented Yes

    Response parameter


    Parameter name Description Notes
    idComment comment id returned
    idJob Job id commented
    Name Job position
    text the comment
    creationDate The create comment date in unix time
    authorEmail email address of the author of the comment
    authorSurName Surname of the author of the comment
    authorName name of the author of the comment

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

        
    GET /api/v1/requests.xml?service_code=004&jobID=48
    Host: penlabor.lynxlab.com
    Content-Type: application/x-www-form-urlencoded; charset=utf-8
    
    service_code=004
    

    Example response:

     
    
    [1]
    0:  {
    idComment: "1_50"
    idJob: "48"
    positionCode: "2.1.1.4.1.3"
    name: "ANALISTA PROGRAMMATORE"
    text: "Questo รจ il testo di commento."
    creationDate: "1392999019"
    locale: null
    authorId: "1"
    authorName: "Maurizio"
    authorSurName: "mazzoneschi"
    authorEmail: "graffio [at] lynxlab [dot ]com"
    }
    
    

    Get opportunities search service


    Get details of the training opportunities

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes 005
    jurisdiction_id jurisdiction_id is only required if the endpoint serves multiple jurisdictions No
    locale Preferred language No language in format en_US, it_IT
    keywords A comma separated list of tags or keywords to help users identify the request type. This can provide synonyms of the service_name and group. No keywords to find a course/training
    city City in which looking for trainings No
    qualification educational qualification of the candidate No

    Response parameter


    Parameter name Description Required Notes
    idTraining unique identifier of a training Yes
    IdTrainingOriginal original unique identifier of a training Yes
    nameTraining name of a training Yes
    trainingCode code of a training Yes
    company the name of the company delivering the training Yes
    trainingAddress address where the course takes place Yes
    zipCode Human entered zip code (CAP in Italy) Yes
    city City where the course takes place No
    phone contact of the company that delivers the training (email, phone, web site) Yes
    durationHours Duration of the training in hours Yes
    trainingType training type Yes
    t_userType the user type to whom the course is aimed Yes
    t_qualificationRequired educational qualification of the candidate Yes
    t_longitude longitude using the (WGS84) projection. Yes
    t_latitude latitude using the (WGS84) projection Yes
    t_dateInsert insertion date of the training Yes
    hash hash code of the training Yes
    t_source email address of the person or his/her id Yes
    t_nation city where the course takes place Yes
    t_minAge minimum age required for the training Yes
    t_maxAge maximum age required for the training Yes
    t_price remuneration offered by the company Yes
    t_reservedForDisabled whether the training is reserved to disable people Yes
    t_favoredCategoryRequests to which kind of disabilities are reserved training Yes only if reserved for disabled is true
    t_notes notes Yes
    t_expiration deadline (in unixtime) to submit the training Yes
    t_linkMoreInfo URL to more info about training offer Yes
    t_media_url URL to media Yes
    locale Preferred language No language in format en_US, it_IT
    sourceTrainingName first name of the person who report the training offer or his/her id Yes
    sourceTrainingSurname last name of the person who report the training offer or his/her id Yes
    t_published whether training offer is published Yes
    t_idNode node of the training Yes

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

    http://devopenlabor.lynxlab.com/api/v1/requests.json?service_code=005

    Example response:

    CAP: "00174",
    city: "ROMA",
    phone: "06/7101749",
    durationHours: "1800",
    trainingType: "QUALIFICA",
    t_userType: null,
    t_qualificationRequired: null,
    t_longitude: null,
    t_latitude: null,
    t_dateInsert: "1392669989",
    hash: "",
    t_source: "",
    t_nation: null,
    t_minAge: null,
    t_maxAge: null,
    t_price: null,
    t_reservedForDisabled: "",
    t_favoredCategoryRequests: null,
    t_notes: null,
    t_expiration: "0",
    t_linkMoreInfo: null,
    t_media_url: "",
    t_locale: "",
    sourceTrainingName: "",
    sourceTrainingSurname: "",
    t_published: "0",
    t_idNode: "2_1"
    },
    

    Post reporting traininig service


    This method is used for sending a training report.

    Request parameter


    Parameter name Description Required Notes
    service_code The unique identifier for the service request type. Yes 006
    jurisdiction_id jurisdiction_id is only required if the endpoint serves multiple jurisdictions No
    locale Preferred language No language in format en_US, it_IT
    nameTraining name of a training Yes
    company the name of the company delivering the training Yes
    trainingAddress address where the course takes place No
    CAP Human entered zip code (CAP in Italy) No
    city City where the course takes place No
    nation City where the course takes place No
    phone contact of the company that delivers the training (email, phone, web site) No
    durationHours Duration of the training in hours Yes
    trainingType training type No the value can be: qualification,specialization,or complete basic school
    userType type of users target No the value can be: adult,underage,or migrant
    qualificationRequired educational qualification of the candidate No
    j_longitude Longitude using the (WGS84) projection. No
    latitude Latitude using the (WGS84) projection. No
    source email address of the person or his/her id Yes
    minAge minimum age required No
    maxAge maximum age required No
    price remuneration offered by the company No
    reservedForDisabled whether the job is reserved to disable people No
    favoredCategoryRequests to which kind of disabilities are reserved job (only if reserved for disabled is true) No
    expiration deadline (in unixtime) to submit the training Yes
    notes notes No
    t_linkMoreInfo URL to more info about training offer No
    media_url URL to media No
    locale Preferred language No language in format en_US, it_IT
    sourceTrainingName first name of the person who report the training offer or his/her id No
    sourceTrainingSurname last name of the person who report the training offer or his/her id No
    published whether job offer is published No

    Response parameter


    Parameter name Description Required Notes
    AddedTrainingId Training id returned Yes

    Possible errors

    The numbers represent the HTTP status code returned for each error type:

    Example request:

        
    POST /api/v1/requests.json
    Host: penlabor.lynxlab.com
    Content-Type: application/x-www-form-urlencoded; charset=utf-8
    
    service_code=006
    

    Example response:

        
    {
    AddedTrainingId: "2700"
    }