Multi-posting (ATS)

Solution API Technical Guide

ATS Integration Documentation.

This document will guide you through the ATS API integration details and implementation process. WhatJobs provides an easy to use API allowing job posters to send the requests to REST interface. The API accepts POST requests which means that any software you write to interact with ATS API must make POST request.

  Formatos de solicitud y respuesta  


Puede usar JSON o XML. Dependiendo de la elección del punto final, los datos presentados deben seguir el mismo formato. Será el mismo para los datos devueltos.

Los endpoints disponibles son los siguientes:

XML endpoint https://uk.whatjobs.com/api/v1/ats/{ats-name} /xml
JSON endpoint https://uk.whatjobs.com/api/v1/ats/{ats-name} /json
Ejemplo https://uk.whatjobs.com/api/v1/ats/your-company-name/xml
 

  Autenticación basada en tokens  


El acceso a la API está restringido a aquellos con un token de acceso. Este token debe ser pasado en un encabezado personalizado HTTP X-API-Token.

Para recuperar su nombre de ATS y el Token de Autenticación, por favor Contactarnos.

 

  Parámetros de solicitud HTTP  


Se puede hacer una solicitud a la versión Sandbox de la API, siempre y cuando se proporcione el siguiente parámetro en la solicitud GET.

Nombre Necesario Descripción
sandbox-mode No Al establecer este parámetro booleano en true, la API funciona en modo sandbox. p.ej. sandbox-mode=true

Solo hay un parámetro HTTP POST necesario.

Nombre Necesario Descripción
data El XML o JSON anexado al cuerpo de la solicitud. Asegúrase de que los datos en el cuerpo del POST corresponden al endpoint al que estás haciendo la solicitud.
La tabla que sigue a continuación entra en más detalles sobre lo que se ha aceptado.
 

  Campos de datos XML/JSON  


Abajo son los campos que pueden ser usados en la solicitud cuando el comando se establece en add.

Nombre del campo Necesario Tipo Información Adicional
command Fix Valor Esperado: add
company_email Email Debe ser indicado con esta etiqueta Admin email address en la página de configuración del portal de empleo.
company_name String Debe ser indicado con esta etiqueta Company name en la página de configuración del portal de empleo.
company_hash String Debe ser indicado con esta etiqueta Hash (Optional) en la página de configuración del portal de empleo.
title String Texto gratis, el título del anuncio. Mínimo 3 caracteres hasta el límite de 255 caracteres.
description String Texto gratis, de 100 a 65k de límite de caracteres, descripción detallada del trabajo.
Este campo puede contener las siguientes tags HTML: p, br, b, strong, i, u, ul, li, ol
job_type SET Valores aceptables: permanent, temporary, contract
job_status SET Valores aceptables: full-time, part-time
application_email Sí, si la url está vacía Email Necesario si application_url está vacía
application_url Sí, si el email está vacío URL Necesario si el application_email está vacío
industry No SET Valores aceptables: Nombre de la industria, valores disponibles en el tablero de abajo.
weeks_to_advertise No SET Valores aceptables: 1, 2, 3, 4, 6, 8, 10, 12
salary_type No SET Valores aceptables: año, mes, semana, día, hora
salary_from No Numeric Un número de fluctuación para el salario más bajo.
salary_to No Numeric Un número de fluctuación para el salario más alto.
salary_currency No SET Valores aceptables: gbp, usd, eur
salary_benefits No String Texto gratuito, información adicional sobre el salario.
location No String Texto gratuito, formato sugerido: país, región, condado, ciudad
postcode No String Código postal válido.
reference No String Texto gratuito, la referencia de trabajo asignada al anuncio por el reclutador.
 

En la tabla de abajo se describen los campos que se pueden utilizar en el orden cuando el comando se establece en borrar.

Nombre del campo Necesario Tipo Información Adicional
command Fix Valor esperado: delete
company_email Email Debe ser indicado con esta etiqueta Admin email address en la página de configuración del portal de empleo.
company_name String Debe ser indicado con esta etiqueta Company name en la página de configuración del portal de empleo.
company_hash String Debe ser indicado con esta etiqueta Hash (Optional) en la página de configuración del portal de empleo.
job_id String Este es el mismo valor que será devuelto en la respuesta de add comando con el siguiente formato: integer-integer
 

  Valores aceptados del sector  


La tabla siguiente contiene todos los valores válidos para el campo del sector.

Sectores
  • Contabilidad
  • Administración y Secretaría
  • Aeroespacial y Aviación
  • Agricultura, Pesca, Silvicultura y Conservación
  • Automoción
  • Servicios Bancarios y Financieros
  • Restauración y Hospitalidad
  • Caridad y Voluntariado
  • Construcción y Propiedad
  • Servicio de Atención al Cliente
  • Defensa y Militar
  • Conducción y Transporte
  • Educación y Formación
  • Electrónica
  • Energía, Utilidades, Petróleo y Gas
  • Ingeniería
  • Moda y Artes
  • Bienes de Consumo
  • Licenciados y Aprendices
  • Salud, Seguridad y Protección
  • Sanidad y Medicina
  • Recursos Humanos y Personal
  • Tecnología de Información
  • Seguros
  • Periodismo, Publicación y Traducción
  • Legal
  • Tranquilidad, Turismo y Entretenimiento
  • Logística y Almacenamiento
  • Gestión y Consultoría
  • Fabricación y Producción
  • Marketing, Publicidad y Relaciones Públicas
  • Media, Diseño y Creatividad
  • Asistente Personal
  • Farmacéutico
  • Sector Público y Gobierno
  • Compras y Adquisiciones
  • Reclutamiento
  • Venta al por Menor y al por Mayor
  • Ventas
  • Científica
  • Asistencia Social
  • Telecomunicaciones
 

  Ejemplo de pedido XML válido  


 
XML Sample for Add Command
          <?xml version="1.0" encoding="UTF-8"?>
          <job>
          <command><![CDATA[add]]></command>
          <company_email><![CDATA[[email protected]]]></company_email>
          <company_name><![CDATA[Sample Company Name]]></company_name>
          <company_hash><![CDATA[]]></company_hash>
          <title><![CDATA[Sample Account Manager]]></title>
          <description><![CDATA[Sample Description ...with html tag support]]></description>
          <industry><![CDATA[Accountancy]]></industry>
          <job_type><![CDATA[permanent]]></job_type>
          <job_status><![CDATA[full-time]]></job_status>
          <weeks_to_advertise><![CDATA[1]]></weeks_to_advertise>
          <application_email><![CDATA[[email protected]]]></application_email>
          <application_url><![CDATA[https://wwww.company.com/valid-url]]></application_url>
          <salary_type><![CDATA[annum]]></salary_type>
          <salary_from><![CDATA[20000]]></salary_from>
          <salary_to><![CDATA[40000]]></salary_to>
          <salary_currency><![CDATA[gbp]]></salary_currency>
          <salary_benefits><![CDATA[Bonus payments]]></salary_benefits>
          <location><![CDATA[England, Yorkshire and the Humber, Yorkshire, Hull]]></location>
          <postcode><![CDATA[]]></postcode>
          <reference><![CDATA[ref-123-xu]]></reference>
          </job>
 
XML cURL Sample for Add Command
            curl https://uk.whatjobs.com/api/v1/ats/{ats-name} /xml?sandbox-mode=true \
            -X POST \
            -H 'x-api-token: {Authentication-Token}' \
            -d 'data=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%3Cjob%3E%3Ccommand%3E%3C!%5BCDATA%5Badd%5D%5D%3E%3C%2Fcommand%3E%3Ccompany_email%3E%3C!%5BCDATA%5Bsample%40email.com%5D%5D%3E%3C%2Fcompany_email%3E%3Ccompany_name%3E%3C!%5BCDATA%5BSample%20Company%20Name%5D%5D%3E%3C%2Fcompany_name%3E%3Ccompany_hash%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fcompany_hash%3E%3Ctitle%3E%3C!%5BCDATA%5BSample%20Account%20Manager%5D%5D%3E%3C%2Ftitle%3E%3Cdescription%3E%3C!%5BCDATA%5BSample%20Description%20...with%20html%20tag%20support%5D%5D%3E%3C%2Fdescription%3E%3Cindustry%3E%3C!%5BCDATA%5BAccountancy%5D%5D%3E%3C%2Findustry%3E%3Cjob_type%3E%3C!%5BCDATA%5Bpermanent%5D%5D%3E%3C%2Fjob_type%3E%3Cjob_status%3E%3C!%5BCDATA%5Bfull-time%5D%5D%3E%3C%2Fjob_status%3E%3Cweeks_to_advertise%3E%3C!%5BCDATA%5B1%5D%5D%3E%3C%2Fweeks_to_advertise%3E%3Capplication_email%3E%3C!%5BCDATA%5Bvalid-email-address%40company.com%5D%5D%3E%3C%2Fapplication_email%3E%3Capplication_url%3E%3C!%5BCDATA%5Bhttps%3A%2F%2Fwwww.company.com%2Fvalid-url%5D%5D%3E%3C%2Fapplication_url%3E%3Csalary_type%3E%3C!%5BCDATA%5Bannum%5D%5D%3E%3C%2Fsalary_type%3E%3Csalary_from%3E%3C!%5BCDATA%5B20000%5D%5D%3E%3C%2Fsalary_from%3E%3Csalary_to%3E%3C!%5BCDATA%5B40000%5D%5D%3E%3C%2Fsalary_to%3E%3Csalary_currency%3E%3C!%5BCDATA%5Bgbp%5D%5D%3E%3C%2Fsalary_currency%3E%3Csalary_benefits%3E%3C!%5BCDATA%5BBonus%20payments%5D%5D%3E%3C%2Fsalary_benefits%3E%3Clocation%3E%3C!%5BCDATA%5BEngland%2C%20Yorkshire%20and%20the%20Humber%2C%20Yorkshire%2C%20Hull%5D%5D%3E%3C%2Flocation%3E%3Cpostcode%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fpostcode%3E%3Creference%3E%3C!%5BCDATA%5Bref-123-xu%5D%5D%3E%3C%2Freference%3E%3C%2Fjob%3E'
          
 
XML Sample for Delete Command
            <?xml version="1.0" encoding="UTF-8"?>
            <job>
            <command><![CDATA[delete]]></command>
            <company_email><![CDATA[[email protected]]]></company_email>
            <company_name><![CDATA[Sample Company Name]]></company_name>
            <company_hash><![CDATA[]]></company_hash>
            <job_id><![CDATA[185394403-1508429206]]></job_id>
            </job>
          
 
XML cURL Sample for Delete Command
            curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/xml?sandbox-mode=true \
            -X POST \
            -H 'x-api-token: {Authentication-Token}' \
            -d 'data=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%3Cjob%3E%3Ccommand%3E%3C!%5BCDATA%5Bdelete%5D%5D%3E%3C%2Fcommand%3E%3Ccompany_email%3E%3C!%5BCDATA%5Bsample%40email.com%5D%5D%3E%3C%2Fcompany_email%3E%3Ccompany_name%3E%3C!%5BCDATA%5BSample%20Company%20Name%5D%5D%3E%3C%2Fcompany_name%3E%3Ccompany_hash%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fcompany_hash%3E%3Cjob_id%3E%3C!%5BCDATA%5B185394403-1508429206%5D%5D%3E%3C%2Fjob_id%3E%3C%2Fjob%3E'
          
 
JSON Sample for Add Command
            {
              "command": "add",
              "company_email": "[email protected]",
              "company_name": "Sample Company Name",
              "company_hash": "",
              "title": "Sample Account Manager",
              "description": "Sample Description ...with html tag support",
              "industry": "Accountancy",
              "job_type": "permanent",
              "job_status": "full-time",
              "weeks_to_advertise": "1",
              "application_email": "[email protected]",
              "application_url": "https://wwww.company.com/valid-url",
              "salary_type": "annum",
              "salary_from": "20000",
              "salary_to": "40000",
              "salary_currency": "gbp",
              "salary_benefits": "Bonus payments",
              "location": "England, Yorkshire and the Humber, Yorkshire, Hull",
              "reference": "ref-123-xu"
            }
 
JSON cURL Sample for Add Command
              curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/json?sandbox-mode=true \
              -X POST \
              -H 'x-api-token: {Authentication-Token}' \
              -d 'data=%7B%22command%22%3A%22add%22%2C%22company_email%22%3A%22sample%40email.com%22%2C%22company_name%22%3A%22Sample%20Company%20Name%22%2C%22company_hash%22%3A%22%22%2C%22title%22%3A%22Sample%20Account%20Manager%22%2C%22description%22%3A%22Sample%20Description%20...with%20html%20tag%20support%22%2C%22industry%22%3A%22Accountancy%22%2C%22job_type%22%3A%22permanent%22%2C%22job_status%22%3A%22full-time%22%2C%22weeks_to_advertise%22%3A%221%22%2C%22application_email%22%3A%22valid-email-address%40company.com%22%2C%22application_url%22%3A%22https%3A%2F%2Fwwww.company.com%2Fvalid-url%22%2C%22salary_type%22%3A%22annum%22%2C%22salary_from%22%3A%2220000%22%2C%22salary_to%22%3A%2240000%22%2C%22salary_currency%22%3A%22gbp%22%2C%22salary_benefits%22%3A%22Bonus%20payments%22%2C%22location%22%3A%22England%2C%20Yorkshire%20and%20the%20Humber%2C%20Yorkshire%2C%20Hull%22%2C%22reference%22%3A%22ref-123-xu%22%7D'
            
 
JSON Sample for Delete Command
              {
                "command": "delete",
                "company_email": "[email protected]",
                "company_name": "Sample Company Name",
                "company_hash": "",
                "job_id": "185394403-1508429206"
              }
 
JSON cURL Sample for Delete Command
                curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/json?sandbox-mode=true \
                -X POST \
                -H 'x-api-token: {Authentication-Token}' \
                -d 'data=%7B%22command%22%3A%20%22delete%22%2C%20%22company_email%22%3A%20%22sample%40email.com%22%2C%20%22company_name%22%3A%20%22Sample%20Company%20Name%22%2C%20%22company_hash%22%3A%20%22%22%2C%20%22job_id%22%3A%20%22185394403-1508429206%22%7D'
              
 

  Códigos de estado de respuesta HTTP  


Dependiendo del resultado de la acción, el código de estado HTTP devuelto puede ser uno de los siguientes valores.

Código de Estado Razón Destinatario del mensaje devuelto Descripción
200 Éxito Usuario final Esto es el resultado de una acción exitosa y el valor de la variable del mensaje devuelto debe ser mostrado al usuario final.
203 Error en los datos de usuario Usuario final Esto ocurre cada vez que el usuario final introduce información no válida. El mensaje devuelto debe ser mostrado al usuario. Por ejemplo, cuando un usuario introduce una dirección de correo electrónico inválida o no tiene suficiente crédito.
400 Bug en la configuración de ATS ATS Esto significa que hubo un problema en la estructura de los datos presentados. Esto ocurre cuando hay un bug en la configuración de ATS. Por ejemplo, el valor del parámetro del comando es algo distinto a add o delete, o el valor del weeks_to_advertise parámetro está fuera de los límites. La razón se puede encontrar en la variable de mensaje devuelta.
503 Error de API ATS El API no está disponible temporalmente y no podría manejar la solicitud por un tiempo. El mensaje devuelto proporciona más información. En este caso, el resultado devuelto puede ser un HTML.
 

  Formato de Respuesta  


La respuesta devuelta será XML o JSON, dependiendo del parámetro seleccionado. Todas las respuestas contendrán las variables siguientes.

Nombre Descripción
success Un valor booleano indica el estado de la respuesta devuelta, que puede ser Verdadero (con el código HTTP de 200) o Falso (con el código HTTP de 203, 400 o 503).
message El mensaje devuelto debe mostrarse al usuario final cuando el código HTTP sea 200 o 203.
job_url Contiene URL de trabajo en el exitoso add ejecución del comando y null por otra parte.
job_id Contiene la identificación del trabajo exitoso add en la ejecución del comando y null por otra parte. Este id debe ser proporcionado en el comando delete.
 

  Ejemplos de Respuestas  


 
Respuesta de éxito XML con código HTTP de 200
                <?xml version="1.0" encoding="UTF-8" ?>
                <response>
                <success><![CDATA[true]]></success>
                <message><![CDATA[The job has been added successfully.]]></message>
                <job_url><![CDATA[https://uk.whatjobs.com/job/sample-job-example-url]]></job_url>
                <job_id><![CDATA[185394449-1508749660]]></job_id>
                </response>
              
 
Respuesta de éxito XML con código HTTP de 200
                <?xml version="1.0" encoding="UTF-8" ?>
                <response>
                <success><![CDATA[true]]></success>
                <message><![CDATA[The job has been deleted successfully.]]></message>
                <job_url><![CDATA[]]></job_url>
                <job_id><![CDATA[]]></job_id>
                </response>
 
Respuesta de error XML con código HTTP de 203
                  <?xml version="1.0" encoding="UTF-8" ?>
                  <response>
                  <success><![CDATA[false]]></success>
                  <message><![CDATA[The company email must be a valid email address.]]></message>
                  <job_url><![CDATA[]]></job_url>
                  <job_id><![CDATA[]]></job_id>
                  </response>
                
 
Respuesta de error XML con código HTTP de 400
                  <?xml version="1.0" encoding="UTF-8" ?>
                  <response>
                  <success><![CDATA[false]]></success>
                  <message><![CDATA[The submitted data is corrupted.]]></message>
                  <job_url><![CDATA[]]></job_url>
                  <job_id><![CDATA[]]></job_id>
                  </response>
 
Respuesta de éxito de JSON con código HTTP de 200
                    {
                      "success": true,
                      "message": "The job has been added successfully.",
                      "job_url": "https://uk.whatjobs.com/job/sample-job-example-url",
                      "job_id": "185394449-1508749660"
                    }
 
Respuesta de éxito de JSON con código HTTP de 200
                      {
                        "success": true,
                        "message": "The job has been deleted successfully.",
                        "job_url": null,
                        "job_id": null
                      }
 
Respuesta de error JSON con código HTTP de 203
                        {
                          "success": false,
                          "message": "The company email must be a valid email address.",
                          "job_url": null,
                          "job_id": null
                        }
 
Respuesta de error JSON con código HTTP de 400
                          {
                            "success": false,
                            "message": "The submitted data is corrupted.",
                            "job_url": null,
                            "job_id": null
                          }
 

  Aplicación  


Dependiendo del método de aplicación cuando un usuario solicita un trabajo, utilizaremos application_email o application_url para enviar los detalles del solicitante a ATS por e-mail; o redirigiremos al usuario a la URL proporcionada. Si ambos valores de las variables están disponibles, el método predeterminado utilizado será la solicitud por e-mail.

 

  Aplicación por formato del correo electrónico  


El correo de aplicación será enviado de una dirección de correo electrónico únicamente generada a la dirección de correo electrónico de aplicación dada, con el siguiente asunto Aplicación para Application for {job-title} - {job-reference}.

El correo electrónico también contiene el reply-to encabezado con la dirección de correo electrónico del usuario final.

El cuerpo del correo electrónico contiene versiones HTML y de texto sin formato. Ambas versiones contienen los campos explicados abajo. Las tags HTML formatean la versión HTML y la versión de texto está en formato JSON.

Nombre del campo Descripción
job_title Título del trabajo
job_reference Referencia del trabajo, si se proporciona.
first_name Nombre del candidato
last_name Apellido del candidato
email_address Correo electrónico del candidato
covering_letter La carta de presentación, si se proporciona.