APIs

Overview

The Jobs APIs are a set of tools that allow companies to integrate their job posting systems with Catho, without the need of posting jobs on the site manually. 


APIs Modeling

All services provided through the API using the REST technology (Representational State Transfer), an architecture for the provision of resources through distributed systems, commonly used over HTTP. Below we can see examples of how services are formed:

 

 

Ilustração modelagem das APIs

Thus:

  • • Hostname: Main Address Services.
  • • API Version: version of the service that is being consumed.
  • • Resource Root: service name.

From the Resource Root, we can access the main operations of the service (CRUD), the standard HTTP methods, as follows:

CRUD HTTP Method
Create POST
Read GET
Update PUT
Delete DELETE
Resource GET POST PUT DELETE
/vagas Jobs list Create new Job * *
/vagas/123 Retrieve the job 123 *** ** * *
/vagas/123/reativada * * Reactivate job 123 *
/vagas/123/renovada * * Renew job 123 *
/vagas/123/desativada * * Disable job 123 *
* The method should not be implemented in collections, then expected to return with ERROR 405 - method not allowed
** The method should not be implemented on items then expected to return with ERROR 405 - method not allowed. However, it is used in the case of an asynchronous call.
*** As the application is an aggregator feature, should return by default all items associated

That is, the service /vagas in the above example, if we make a GET operation, we get an answer a list of jobs and, if we make a POST, we will save a new wave (available only in Sandbox environment).


HTTP 1.1

The standard protocol for communication with the APIs is the HTTP version 1.1. For more information about this protocol, see:

http://www.w3.org/Protocols/rfc2616/rfc2616.html
http://www.ietf.org/rfc/rfc2616.txt


UTF-8

The charset standard for calls to APIs is UTF-8.

For more information about this encoding, see:

https://tools.ietf.org/html/rfc3629


JSON

JSON (JavaScript Object Notation) is a standard open format that uses text to transmit data between a server and web application as an alternative to XML.

By default all API JSON travels, both to receive information (POST and PUT methods) and in return (GET method).

Because of this standardization, for POST and PUT calls, you must inform two parameters in the Header:

• Accept: application / json
• Content-Type: application / json

Otherwise, you receive an HTTP Error 415: Unsupported Media Type.


Endpoints

There are two endpoints to access the API services: use the Production endpoint only when your application is published, and while their application is developed, use the endpoint Sandbox.

To access Production, use the URL below:

https://api.catho.com.br/v1/vagas/

To test the Sandbox services, use the URL below:

http://sandbox.catho.com.br/v1/vagas/


 

HTTP Status

The HTTP codes below indicate successfully returns:

• HTTP 200: Indicates that processing was performed correctly and the return will be as expected.
• HTTP 201: Indicates that the object sent in the request body was included.

The HTTP codes below indicate returns with error:

• HTTP 400: Invalid Request.
• HTTP 401: Invalid Authentication.
• HTTP 403: Authentication denied.
• HTTP 404: Not Found.
• HTTP 405: Method Not Allowed.
• HTTP 408: Timeout.
• HTTP 409: Conflict.
• HTTP 413: Request Exceeds Maximum Filesize.
• HTTP 415: Media Type Invalid.
• HTTP 422: Business Exceptions.
• HTTP 500: Internal Server Error.


Erros de validação

These errors prevent the realization of the submitted action, to forward the request is necessary to change the body data, header or URL parameters, as instructed by giving an error.

See an example in the field "title" was not informed in the POST body:

https://api.catho.com.br/v1/vagas/:

{
    erros:
    {
        E010201: "Invalid Title."
    }
}

Below is the list of all the errors that can be returned:

Code Message
E010000 job does not belong to the company.
E010201 field 'title' invalid.
E010202 field 'title' should be a maximum of 255 characters.
E010301 Field 'activities' is required.
E010401 Field 'regimeContratacao' should be an array.
E010402 Number of items 'regimeContratacao' exceeded the limit 2.
E010501 Field 'benefits' should be an array.
E010801 Field invalid 'type' expected value 'NEW' or 'REPLACEMENT'.
E011001 Field 'period' of 'stage' must have the 'FULL' values, 'DAY', 'evening' or 'NIGHT'.
E011003 Field 'finaisSemana' to 'stage' must be of type 'boolean'
E011101 field 'value' of 'salary' uninformed.
E011102 field 'value' of 'salary' should be a number.
E011104 Salary range 'id' not registered.
E011105 Field 'confidential' from 'wage' must be of type 'boolean'.
E011201 The field 'recruiters' must be of type 'array'.
E011202 field 'email' from 'recruiters' invalid.
E011204 field 'email' from 'recruiters' invalid.
E011205 The size of the field 'email' from 'recruiters' exceeded the maximum size.
E011206 Recruiter not found.
E011301 It is not allowed to repeat cities.
E011302 not allowed to inform the Brazil when it passes a list of countries.
E011303 It is mandatory to inform at least one type of valid per seat location.
E011305 Location not found.
E011306 field 'type' of 'locality' uninformed.
E011307 field 'type' of 'locality' should have the value 'PARENTS' or 'CITY'.
E011310 The field 'local' from 'location' must be of type 'array'.
E011311 field 'name' of 'local' from 'location' is required.
E011312 field 'name' of 'local' from 'locality' should be up to 255 characters.
E011313 field 'name' of 'local' from 'location' must be of type 'string'.
E011316 Field 'amount' of 'local' from 'location' must be greater than 0.
E011318 Field 'amount' of 'local' from 'location' is required.
E011321 Field 'uf' from 'local' from 'location' is required.
E011322 Field 'uf' from 'local' from 'location' must have 2 characters.
E011323 Field 'uf' from 'local' from 'location' must have 2 characters.
E011324 Field 'uf' from 'local' from 'location' must be of type 'string'.
E011326 City / State not found.
E011327 Parents not found.
E011401 field 'name' of 'contractor' uninformed.
E011402 field 'name' of 'contractor' must be up to 255 characters.
E011403 field 'name' of 'contractor' must be of type 'string'.
E011405 Name invalid contractor.
E011406 Field 'branch' of 'contractor' uninformed.
E011407 Field 'branch' must be of type 'integer'.
E011408 invalid type.
E011410 Field 'nationality' of 'contractor' informed.
E011411 Field 'nationality' of 'contractor' must have the value 'NATIONAL' or 'MULTINATIONAL'.
E011413 field 'size' of 'contractor' uninformed.
E011414 field 'size' of 'contractor' must have the value 'P', 'M', 'G'.
E011416 field 'description' of 'contractor' uninformed.
E011417 Field 'confidential' from 'contractor' must be of type 'boolean'.
E011418 The field 'contractor' must be of type 'object'.
E011500 The field 'languages' of 'requirements' must be of type 'array'.
E011501 The field 'requirements' must be of type 'object'.
E011504 Field 'level' of 'languages' of 'requirements' is required.
E011505 Field 'level' of 'languages' of 'requirements' should have 1, 2 or 3.
E011506 The field 'stage' of 'requirements' must be of type 'object'.
E011507 field 'year' to 'stage' of 'requirements' must be of type 'array'
E011508 The value of the array is not of the required type.
E011509 field 'year' to 'stage' of 'requirements' can be up to 6 items.
E011510 The "education" of "requirements" is required when the position of the vacancy is intern profile.
E011602 Field 'question' of 'questionnaire' is required.
E011603 Field 'type' 'questionnaire' is required.
E011604 Field 'type' 'questionnaire' should have the value 'ALTERNATIVE' or 'Essay'
E011605 Field 'answers' from 'questionnaires' must have the value 'S' or 'N'.
E011606 The field 'questionnaire' must be of type 'array
E011607 In 'questionnaire' field are allowed a maximum of 5 items.
E011701 The 'PCD' field must be of type 'object'.
E011702 Field 'type' 'PCD' is required.
E011703 Field 'type' 'PCD' must have the value 'PHYSICAL', 'Hearing', 'VISUAL', 'MENTAL' or 'MULTIPLE'.
E011705 field 'description' of 'PCD' is required.
E011706 The field 'options' from 'PCD' must be of type 'object'.
E011707 Field 'companion' of 'options' from 'PCD' must be of type 'boolean'.
E011708 Field 'braille' from 'options' from 'PCD' must be of type 'boolean'.
E011709 Field 'instalacoesAdaptadas' from 'options' from 'PCD' must be of type 'boolean'.
E011710 Field 'leituraLabial' from 'options' from 'PCD' must be of type 'boolean'.
E011711 Field 'pounds' from 'options' from 'PCD' must be of type 'boolean'.
E011712 Field 'transporteColetivo' from 'options' from 'PCD' must be of type 'boolean'.
E011713 Field 'veiculoAdaptado' from 'options' from 'PCD' must be of type 'boolean'.
E011802 Field 'sex' to 'filter' should have the value 'M' or 'F'.
E011804 Age can not be less than 18 or greater than 80 years
E011806 The field 'location' of 'filters' must be of type 'object'.
E011807 field 'type' of 'places' of 'filters' must have the value 'STATE', 'REGION' or 'CITY'.
E011808 Field 'criterion' of 'location' of 'filters' must be of type 'array'.
E011811 Field 'uf' of 'criteria' of 'location' of 'filters' must have 2 characters.
E011812 Field 'uf' of 'criteria' of 'location' of 'filters' must have 2 characters.
E011813 No criteria for the filter age was informed.
E011902 Field 'alertaEmail' from 'configurations' must be of type 'boolean'.
E011903 Field 'anuncianteConfidencial' from 'configurations' must be of type 'boolean'.
E020001 job not found.
E020002 Oops, this job has been disabled.
E020101 Field 'hired' can not be empty.
E020102 Field 'hired' should receive a value of type boolean.
E020201 The field 'name' must be given a value of type 'array'.
E020202 The 'name' field should receive an 'array' with 'strings'.
E030000 The subject should be one of the following values: POUCOS_CURRICULOS, FORA_PERFIL, VAGA_ABERTA, MAIS_CANDIDATOS, DISPONIVEL_NOVAMENTE
E030001 job not found.
E030002 Oops, that vacancy has 50 days notice.
E030003 Oops, this job can not be renewed because it is not active.
E030005 Oops, that job has already been renewed.
E040000 Oops, the vacancy can not be reactivated.
E040001 job not found.

 


Warnings

Warnings are informational messages associated with certain characteristics of the vacancy. Unlike errors, warnings do not prevent the insertion of the vacancy.

Remember that although they did not prevent the insertion of vague warnings should be treated because they relate to the quality of this vacancy. Jobs with many warnings tend to be rejected by our inspection.

Code Message
W010401 repeated Hiring schemes were unified.
W010402 seasonal temporary jobs are outside the scope Catho.
W010403 invalid procurement regime identifier.
W010501 repeated Benefits were unified.
W010502 benefit Identifier '' invalid.
W011101 recommend not advertise jobs with salary less than R $ 100.00.
W011102 The range of payment chosen, above R $ 3,000.00, is not the most appropriate for apprenticeship positions.
W011103 The range of payment chosen, below R $ 1,000.00, is not the most suitable for board and management positions.
W011201 The email '' was not found.
W011401 recommend that you only advertise vacancies confidential if it is to replace any employee has not turned off.
W011501 information repeated in the description field (knowledge / experiences / activities).
W011502 repeated Languages ​​were unified.
W011503 Language '' not found.
W011504 year stage 'id' invalid and ignored.
W011601 The filter may be used to alternative questions.
W011602 The question '' is repeated.
W011701 PCD Skill '' not compatible with the type of disability informed
W011801 Jobs cities with filter can receive few resumes. More comprehensive filters, such as state or region, increase the chances of receiving more resumes.
W011802 The location filter, the region with name '' and State '' was not found.
W011803 The location filter, the city '' was not found for UF ''.
W011804 To use the location filter is necessary to inform at least one city to the vacancy.
W011805 City '' repeat the filters.
W011806 Field '' not informed. Filter not registered.
W011901 It is not possible to highlight this job in working with us as 'available' field is false.
W011902 Data 'Careers' ignored. To use the 'Careers' you need to have configured product.

Pagination

When viewing the results of some API methods you can choose to use paging parameters. To page results you can choose to use two parameters in the query string itself, "page" and "pageSize" as shown below:

https://api.catho.com.br/api/v1/vagas?page=1&pageSize=10

Thus, as a result, we have a list of 10 objects from the list first. If you do not use the paging parameters, by default, the return is always with 10 items per page.

Below are all parameters that can be passed via the URL:

dataCadastro: Period of vacancies (only in GET):

 

page: Indicates the current page of the consultation;

pageSize: Indicates the number of records per page;

Below are some of the main properties of the result:

page_count: page count in the query result;

page_size: Maximum number of items per page;

total_items: Number of items from the query result;

_links: Are the navigation references to the pages:

  • self: current page
  • first: first page
  • last: last page
  • next: next page
  • prev: previous page

At the jobs list, 

links: 
{
self: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=2"
}
-
listagemCatho: 
{
href: "https://seguro.catho.com.br/login/index.php?redir=http://www.catho.com.br/area-empresa/minhas-vagas/"
}
-
first: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10"
}
-
last: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=98"
}
-
prev: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=1"
}
-
next: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=3"
}
-
}

No retorno unitário da vaga,

_links:
{
self: 
{
href: "https://api.catho.com.br/vagas/vagas/9230196/"
}
-
visualizacaoCatho: 
{
href: "https://seguro.catho.com.br/login/index.php?redir=http://www.catho.com.br/area-empresa/painel-vagas/9230196/"
}
-
}

_embedded: These are the main feedback information data, in which case the openings.


Published jobs flow

Just below it is possible to understand what the life cycle of a vacancy in the Catho site.

Ilustração fluxo de vaga publicada

Register Job: This flow explains the wave cycle at CareerBuilder. He contemplates since its inclusion to the steps that the wave passes when in the air.

Inspection: Once a job is included, it is inspected by our Jobs Inspection team. It is a specialized team in the analysis of descriptions of places and identifying possible problems, thus ensuring the quality of vacancies posted on the Monster site.

Approved job: Cool! Vacancies follows our quality standards and will be available on the website.

Vacancy rejected: Oops, there was a problem. His job was not approved in any of the inspection criteria and will not be available for candidates send resumes. This job should not be sent back without the necessary changes are made.

Published: Very well! His job passed inspection and is already in the air. Now your job can be viewed by our candidates, who can register in your selection process.

Renewal: The vacancies are on the site for 60 days and can be renewed for a further period, between the 50th and the 60th day. Much attention: only a vague 'Posted' can be renewed and this can only be done ONCE.

Wave off: Jobs that are not renewed within the period of 60 days will be disabled and will not appear on the Monster site.

Reactivation: If your place is disabled, you can reactivate it so it will return to the site.


Data table refference

Here we can see the tables of data references of past fields as parameter.

Salary

It is used in resource GET and POST / jobs / in salario.valor field given rule: when the salary is below 50 means that a track was used for the salary. Check out the values of each salary range:

Value Description
2 max R$ 1.000,00
3 from R$ 1.001,00 to R$ 2.000,00
4 from R$ 2.001,00 to R$ 3.000,00
5 from R$ 3.001,00 to R$ 4.000,00
6 from R$ 4.001,00 to R$ 5.000,00
7 from R$ 5.001,00 to R$ 6.000,00
8 from R$ 6.001,00 to R$ 7.000,00
9 from R$ 7.001,00 to R$ 8.000,00
10 from R$ 8.001,00 to R$ 9.000,00
11 from R$ 9.001,00 to R$ 10.000,00
12 from R$ 10.001,00 to R$ 15.000,00
13 from R$ 15.001,00 to R$ 20.000,00
14 Beyond R$ 20.000,00

Branches

It is used in resource GET and POST / jobs / in contratante.ramo field. Check out the values of each branch:

Valor Descrição
2 Education/Languages
3 Food
4 Petrochemistry
5 Pharmacology/Veterinary
6 Human Resources
7 Graphic/Editorial
8 Accounting/ Auditing
9 Importation/ Exportation
10 Public relation
11 Automotive
12 Informatic
13 Aesthetics/ Gym
14 Rubber
15 Health
16 Civil construction
17 Legal
18 Services provider
19 Beverages
20 Electronic
21 Advertising
22 Telecomunications
23 Engineering
24 Textile
25 Entertainment
26 Tourism/Hotels
27 Others
28 Transport
29 Paper
30 Agriculture
31 Public organs
32 Brokerage
33 Bank
34 Comunication
35 Automation
36 Consumer goods
37 Capital Goods
38 Wholesale
39 Sales
40 Cosmetics
41 dealership
42 Brokerage (houses)
43 Brokerage (real state)
44 Packages
45 Financial
46 Industry
47 Internet/ Sites
48 Mechanics
49 Metalurgical
50 Syndicate
51 Plastic
52 Restaurant/Fast Foot
53 Insurance / Private pension
54 Asset security
55 Telemarketing/ Call Center
56 Coffee
57 Suggar and Alcohol
58 Logistics / Warehouses
59 Tourism
60 Market
61 Administration
62 Energy
63 Building materials
64 Wood
65 Footwear
66 Mining
67 Medical Equipments
68 News
69 Office goods
70 Industrial Equipment
71 Furniture and decorative
72 Gym and Martial arts
73 Consulting
74 Events
75 Commercial Representation
76 Architecture / Landscape / Urbanism
77 Press Office
78 Merging

Languages

It is used in resource GET and POST / jobs / in requisitos.idiomas.nome given rule field: The requisitos.idiomas takes an array of objects that contains the field name. Check out all acceptable languages:

Description
English
Spanish
French
Deustch
Italian
Romanian
Greek
Russian
Japanese
Chinese
Hebrew
Swedish
Korean
Arabic

Hiring Scheme

It is used in resource GET and POST / jobs / in regimeContratacao field. Check out all acceptable schemes:

Value Description
1 Autonomous
2 CLT (Hired)
5 Free-lancer
6 Services (PJ)
7 Temporary
8 Trainee

Benefits

It is used in resource GET and POST / jobs / benefits in the field. Check out all acceptable benefits:

Value Description
1 Health Insurance
2 Medical assistance
3 Dental Care
4 Agreement with Pharmacy
5 Group Life Insurance
6 Meal ticket
7 Food ticket
8 Basic suplies
9 Car
10 Parking
11 Fuel
12 Private pension
13 Day care
14 School Study
15 Study graduate / MBA
16 Languages study
17 Mobile phone provided by company
18 Transportation provided by company
19 Restaurant
20 Transport Ticket
21 Profit Sharing