REST API DE RH

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 5 min. de leitura

    • . RH REST A API fornece endpoints que retornam informações sobre funcionários que trabalham ou vivem nos Estados Unidos.

    Para acessar esta API, você deve ter a função sn_hr_core.usa_employee_only e o plug-in App com escopo de recursos humanos: Core (com_sn_hr_core) ativados.

    RH REST - OBTENHA /get_usa_employee_profile

    Retorna informações de perfil do funcionário para funcionários baseados nos Estados Unidos.

    As informações retornadas podem ser:
    • Informações de perfil do funcionário para um ID de funcionário especificado.
    • Informações para funcionários que foram adicionados ou cujas informações foram atualizadas em ou após uma data especificada.
    Nota:
    Os funcionários devem ter seu país de trabalho ou de origem especificado como os Estados Unidos para que este endpoint os inclua nos resultados de retorno.
    Além disso, o endpoint envia os seguintes parâmetros para a aplicação CIC Plus integrada (consulte a seção Retornos para obter descrições):
    • EmployeeIdentifier
    • Nome
    • MiddleName
    • Sobrenome
    • E-mail
    • WorkAddress
    • WorkCity
    • WorkState
    • WorkPostalCode
    • WorkCountry
    • Endereço residencial
    • Cidade inicial
    • HomeState
    • HomePostalCode
    • País de origem
    • Data de nascimento
    • HireDate

    Formato de URL

    URL padrão: /api/sn_hr_core/hr_rest_api/get_usa_employee_profile

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    Nenhum(a)
    Tabela 2. Parâmetros de consulta
    Parâmetro Descrição
    employee_identifier Identificador exclusivo de um funcionário. O sistema de chamada gera este valor e pode estar em qualquer formato que seja consistente com seu sistema. Para obter esse valor, chame primeiro o endpoint usando updated_afterparâmetro.
    Nota:
    Este parâmetro é mutuamente exclusivo com updated_afterparâmetro. Este parâmetro define um funcionário exclusivo, enquanto updated_afterretorna um grupo de funcionários criados/atualizados após uma data especificada.

    Tipo de dados: Cadeia de caracteres
    sysparm_limit Número máximo de registros a serem retornados. Para solicitações que excedem esse número de registros, use sysparm_offsetparâmetro para paginar a recuperação de registro.

    Tipo de dados: Número

    Padrão: 1000
    sysparm_offset Índice de registro inicial para o qual começar a recuperar registros. Use este valor para paginar a recuperação de registro. Esta funcionalidade permite a recuperação de todos os registros, independentemente do número de registros, em pequenos blocos gerenciáveis.

    Por exemplo, na primeira vez que você chamar este endpoint, sysparm_offsetdefinido como "0". Para simplesmente percorrer todos os registros disponíveis, use se você não tiver certeza de que você está usando o sysparm_offset até chegar ao final de todos os registros.
    updated_after Data a ser usada para determinar os dados do funcionário a serem retornados. Todos os funcionários baseados nos Estados Unidos (do trabalho ou em casa) que foram adicionados à sua instância ou cujas informações foram atualizadas em ou após essa data, são incluídos nos resultados de retorno.
    Nota:
    Este parâmetro é mutuamente exclusivo com employee_identifierparâmetro.

    Tipo de dados: Cadeia de caracteres

    Formato: AAAA-MM-DD HH:MM:SS ou AAAA-MM-DD (o tempo padrão é 00:00:00)
    Tabela 3. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    Nenhum(a)

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Próxima página Sinalizador que indica se há dados adicionais a serem obtidos em uma chamada subsequente. Por exemplo, se houver um total de 120 registros de funcionários que correspondam aos critérios de pesquisa e sysparm_limit estiver definido como 100, então Next-Pageverdadeiro. Se não houver resultados adicionais disponíveis, Next-Pagefalso.
    Valores válidos:
    • Verdadeiro: Dados adicionais estão disponíveis, outra chamada deve ser feita para obter o próximo bloco de dados.
    • Falso: Não há dados adicionais.

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da REST API .

    Tabela 6. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Elemento Descrição
    Data de nascimento Data de nascimento do funcionário.

    Tipo de dados: Cadeia de caracteres
    Empresa Nome da empresa.

    Tipo de dados: Cadeia de caracteres
    E-mail Endereço de e-mail do funcionário.

    Tipo de dados: Cadeia de caracteres
    EmployeeIdentifier Identificador exclusivo do funcionário.

    Tipo de dados: Cadeia de caracteres
    Nome Nome do funcionário.

    Tipo de dados: Cadeia de caracteres
    HireDate Data em que o funcionário foi contratado.

    Tipo de dados: Cadeia de caracteres
    Sobrenome Sobrenome do funcionário.

    Tipo de dados: Cadeia de caracteres
    MiddleName Nome do meio do funcionário.

    Tipo de dados: Cadeia de caracteres
    Recontratar Para uso futuro.

    Tipo de dados: Cadeia de caracteres
    ResidenceAddress Endereço residencial do funcionário.

    Tipo de dados: Cadeia de caracteres
    ResidenceCity Cidade de residência do funcionário.

    Tipo de dados: Cadeia de caracteres
    ResidenceCountry País de origem do funcionário.

    Tipo de dados: Cadeia de caracteres
    ResidencePostalCode CEP residencial do funcionário.

    Tipo de dados: Cadeia de caracteres
    ResidênciaState Estado de residência do funcionário.

    Tipo de dados: Cadeia de caracteres
    Sufixo Sufixo do funcionário, como Sr., Sra. Ou Dr.

    Tipo de dados: Cadeia de caracteres
    WorkAddress Endereço comercial do funcionário.

    Tipo de dados: Cadeia de caracteres
    WorkCity Cidade de trabalho do funcionário

    Tipo de dados: Cadeia de caracteres
    WorkCountry País de trabalho do funcionário.

    Tipo de dados: Cadeia de caracteres
    WorkPostalCode CEP de trabalho do funcionário.

    Tipo de dados: Cadeia de caracteres
    WorkState Estado de trabalho do funcionário.

    Tipo de dados: Cadeia de caracteres

    Solicitação de cURL de amostra para informações de um funcionário específico

    curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?employee_identifier=231"
-H "accept: application/json" \
-u "username":"password"
    {"result": [
 {
  "EmployeeIdentifier": "231",
  "FirstName": "Harold",
  "MiddleName": "William",
  "LastName": "Lewis",
  "Suffix": "Mr.",
  "Email": "Howard.Lewis@example.com",
  "BirthDate": "",
  "HireDate": "2021-02-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
 }
]}

    Solicitação de cURL de amostra para uma lista de funcionários adicionados/atualizados em ou após 18/2019/05

    curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?update_after=2019-05-18"
-H "accept: application/json" \
-u "username":"password"
    {"result": [
 {
  "EmployeeIdentifier": "2345",
  "FirstName": "Cheryl",
  "MiddleName": "Lynn",
  "LastName": "Smith",
  "Suffix": "Mrs.",
  "Email": "Cheryl.Smith@example.com",
  "BirthDate": "",
  "HireDate": "2019-06-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
  },
  {
  "EmployeeIdentifier": "1111",
  "FirstName": "Thomas",
  "MiddleName": "",
  "LastName": "Doe",
  "Suffix": "Mr.",
  "Email": "Thomas.Doe@example.com",
  "BirthDate": "1978-05-22",
  "HireDate": "2019-08-14",
  "Company": "",
  "ResidenceAddress": "",
  "ResidenceCity": "San Jose",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "13308 Midland Road, Poway",
  "WorkCity": "Poway",
  "WorkState": "CA",
  "WorkPostalCode": "",
  "WorkCountry": "USA",
  "ReHire": ""
  }
]}