# API VaaS /Vagas as a Service/ OpenAPI file: https://vaas.vag.as/doc/publicacao-vagas-vaas-en.yaml ## Description This is version `1.0.0` of this API documentation. Last update on Sep 22, 2026. ## Introduction VaaS (Vagas as a Service) acts as a true recruitment agent, enabling any software platform to leverage the Intelligent Job Posting feature. Through VaaS, Vagas.com clients who use third-party software can automatically publish job openings on Vagas.com via an HTTP request in JSON format. Unlike the traditional job posting process, this API allows an external application URL to be included in the job posting, redirecting candidates to another system when they click to apply. Another key feature of VaaS is the ability for authorized partners to publish jobs on behalf of their clients. In such cases, the partner can make API requests within the Vagas.com ecosystem using the represented company's information, enabling job postings to be created and managed for third parties, provided the appropriate authorization has been granted. ## Technical Requirements **Data Delivery** - Contract Format: JSON - Encoding: UTF-8 - Authentication: OAuth 2.0 / API Key - Transport Security: TLS 1.2 - Protection Mechanisms: CSRF Protection, Rate Limiting. Web Application Firewall (WAF) **Client Requirements** - Support for TLS 1.2 - Support for HTTP 1.2 (or the applicable HTTP version) - Configurable timeout and retry policies - Identifiable User-Agent: X-Idempotency-Key / X-Client-Id / X-Tenant-Id ## Authentication The authentication for using this API can be done in two ways: - Client Credencials - The job will be created with user identification of _admin_ as responsible - Autorization Code (3-legged) - The job will be created with the given user in the authorization steps as responsible ### Client Credencials This process consists of a direct POST call to the gateway indicating the credentials to obtain the access token. Considering that the credentials were created in the gateway, just make a call according to the example: ``` curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded' -i 'https://apigateway.vagas.com.br/oauth/token' --data 'grant_type=client_credentials' -u 'client_id:client_secret' ``` The return will be: ```json { "access_token": "asd23sde12e123sd", "expires_in": 2591999, "token_type": "Bearer" } ``` For all other requests below, the __access\_token__ must be included in the request as a Authorization HEADER attribute in BEARER token format Remembering that __access\_token__ has a time limit for use, the information returned in the key __expires\_in__ indicates the number of seconds that the token will expire from its generation date. __Exemple request using the __access\_token__:__ ```shell # Example token the must be added in the Authorization HEADER: # Authorization: Bearer asd23sde12e123sd CURL example: curl -XGET --header “Authorization: Bearer asd23sde12e123sd” ``` ### Autorization Code (3-legged) This process implements the OAuth 2.0 specification for authentication and authorization. The authentication uses the Authorization Code (Three-Legged OAuth) flow, in which the client system redirects the user (registered in Vagas.com) to the Vagas API authorization server. #### How to get the token The remote service starts the process by calling the PATH /oauth/authorize from the Vagas API server, sending as parameters: - __client_id__: Application ID (Provided by Vagas team) - __login_type__: Type of login ID (must send the value "empresa") - __response_type__: Type of response ID (must send "code") - __redirect_uri__: URI that will be redirected when login action succeeds or fails __Exemple:__ ``` https://apigateway.vagas.com.br/oauth/authorize?response_type=code&client_id=some_application_id&login_type=empresa&redirect_uri=http%3A%2F%2Flocalhost%2Foauth%2Fcode_callback ``` The user will authenticate with their credentials and authorize the use of their information by the remote service. When the user accepts the authorization, the Vagas API server will redirect back to the remote service using the address indicated by the redirect_uri parameter with an authorization code. __Exemple:__ ``` http://localhost/oauth/code_callback?code=AixUbVTop239876 ``` In case of unauthorized request, the call will be to the same URI informed in the redirect_uri parameter with the error parameter. __Exemple:__ ``` http://localhost/oauth/code_callback?error=unauthorized-request ``` Using the code returned above, the remote service must request an access token that will be used for all other requests. Making a new request via an HTTP POST to the route /oauth/token using the "application/x-www-form-urlencoded" format with the following parameters: - __code__: The authorization code (received in the previous request) - __grant_type__: Should have the value: "authorization_code" It must also be included in the request HEADER an attribute with the client\_id and client\_secret information concatenated by a colon (:) and encoded in Base64 __Example:__ - Having the client\_id equal to __"example"__ and a client\_secret equal to __"emi40QrBjUiPaVC2eGK5"__ - Must be concatenated: __example:emi40QrBjUiPaVC2eGK5__ - Applied Base64 on above value: __ZXhhbXBsZTplbWk0MFFyQmpVaVBhVkMyZUdLNQ==__ - Included in the HEADER of the request: __Authorization: Basic ZXhhbXBsZTplbWk0MFFyQmpVaVBhVkMyZUdLNQ==__ __Exemple Curl:__ ```shell curl -XPOST https://apigateway.vagas.com.br/oauth/token \ --header “Authorization: Basic ZXhhbXBsZTplbWk0MFFyQmpVaVBhVkMyZUdLNQ==” \ --data “code=AixUbVTop239876&grant_type=authorization_code” ``` __The return of the request, if successful will be:__ ```json { "access_token": "asd23sde12e123sd", "expired_in": 2591999 } ``` For all other requests below, the __access\_token__ must be included in the request as a HEADER attribute in BEARER format Remembering that __access\_token__ has a time limit for use, the information returned in the key __expires\_in__ indicates the number of seconds that the token will expire from its generation date. __Example call using __access\_token__:__ ```shell # Example value that must be included in the request HEADER: # Authorization: Bearer asd23sde12e123sd CURL example: curl -XGET --header “Authorization: Bearer asd23sde12e123sd” ``` ## Servers - https://apigateway.vagas.com.br/v1: https://apigateway.vagas.com.br/v1 () ## Topics ### [Authentications](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/authentication.md) ## Endpoints ### [VaaS](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/group/endpoint-vaas.md) - [Post Job](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-postjobvaas.md) - [Update Job](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-updatejobvaas.md) - [Update Represented Job Posting](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-updaterepresentedjobvaas.md) - [Suspend Job](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-suspendjobvaas.md) ### [Lists](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/group/endpoint-lists.md) - [List Presentations](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listpresentationsvaas.md) - [List Fields of Activity](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listfieldsofactivityvaas.md) - [List Benefits](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listbenefitsvaas.md) - [List Partner channels](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listpartnerchannelsvaas.md) - [List Cities](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listcitiesvaas.md) - [List Company Divisions](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listcompanydivisionsvaas.md) - [List States](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-liststatesvaas.md) - [List Phases](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listphasesvaas.md) - [List Languages](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listlanguagesvaas.md) - [List Work model](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listworkmodelvaas.md) - [List Education Levels](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listeducationlevelsvaas.md) - [List Hierarchical Levels](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listhierarchicallevelsvaas.md) - [List Countries](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listcountriesvaas.md) - [List Contract Type](https://vaas.vag.as/doc/publicacao-vagas-vaas-en/operation/operation-listcontracttypevaas.md) [Powered by Bump.sh](https://bump.sh)