API REST RH

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 5 minutes de lecture

    • L’API REST RH fournit des points de terminaison qui renvoient des informations sur les employés qui travaillent ou vivent aux États-Unis.

    Pour accéder à cette API, le rôle sn_hr_core.usa_employee_only et le module d’extension Human Resources Scoped App : Core (com_sn_hr_core) doivent être activés.

    HR REST : OBTENIR /get_usa_employee_profile

    Renvoie les informations sur le profil des employés basés aux États-Unis.

    Les informations renvoyées peuvent être :
    • Informations sur le profil de l’employé pour un ID d’employé spécifié.
    • Informations pour les employés qui ont été ajoutés, ou dont les informations ont été mises à jour, à une date spécifiée ou après.
    Remarque :
    Les employés doivent indiquer leur pays de travail ou d’origine en tant que États-Unis pour que ce point de terminaison les inclue dans les résultats de renvoi.
    En outre, le point de terminaison envoie les paramètres suivants à l’application CIC Plus intégrée (voir la section Retours pour les descriptions) :
    • Identificateur de l’employé
    • Prénom
    • Deuxième prénom
    • Lastname
    • E-mail
    • Adresse de travail
    • Ville de travail
    • État de travail
    • Code postal de travail
    • Pays de travail
    • Adresse du domicile
    • Ville natale
    • État d’origine
    • HomePostalCode
    • Pays d’origine
    • Naissance
    • HireDate

    Format d'URL

    URL par défaut : /api/sn_hr_core/hr_rest_api/get_usa_employee_profile

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    Nom Description
    Aucun
    Tableau 2. Paramètres de requête
    Paramètre Description
    employee_identifier Identificateur unique d’un employé. Le système appelant génère cette valeur et peut être dans n’importe quel format compatible avec son système. Pour obtenir cette valeur, appelez d’abord le point de terminaison à l’aide du updated_after paramètre.
    Remarque :
    Ce paramètre est mutuellement exclusif avec le updated_after paramètre. Ce paramètre définit un employé unique, tandis que updated_after renvoie un groupe d’employés créés/mis à jour après une date spécifiée.

    Type de données : chaîne
    sysparm_limit Nombre maximal d'enregistrements à renvoyer. Pour les demandes qui dépassent ce nombre d'enregistrements, utilisez le paramètre sysparm_offset pour paginer la récupération d'enregistrements.

    Type de données : nombre

    Par défaut : 1 000
    sysparm_offset Index de début des enregistrements pour lequel commencer à récupérer des enregistrements. Utilisez cette valeur pour paginer la récupération des enregistrements. Cette fonctionnalité permet de récupérer tous les enregistrements, quel que soit le nombre d'enregistrements, par petits blocs gérables.

    Par exemple, lors du premier appel de ce point de terminaison, sysparm_offset est défini sur « 0 ». Pour parcourir simplement tous les enregistrements disponibles, utilisez le paramètre sysparm_offset=sysparm_offset+sysparm_limit, jusqu'à atteindre la fin de tous les enregistrements.
    updated_after Date à utiliser pour déterminer les données de l’employé à renvoyer. Tous les employés basés aux États-Unis (professionnels ou domicile) qui ont été ajoutés à votre instance, ou dont les informations ont été mises à jour à compter de cette date, sont inclus dans les résultats de renvoi.
    Remarque :
    Ce paramètre est mutuellement exclusif avec le employee_identifier paramètre.

    Type de données : chaîne

    Format : AAAA-MM-JJ HH :MM :SS ou AAAA-MM-JJ (l’heure par défaut est 00 :00 :00)
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    Néant

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir une liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 5. En-têtes de réponses
    En-tête Description
    Page suivante Marqueur indiquant s’il existe des données supplémentaires à obtenir lors d’un appel ultérieur. Par exemple, si un total de 120 enregistrements d’employés correspondent aux critères de recherche et que sysparm_limit est défini sur 100, alors Next-Page la valeur est vrai. Si aucun résultat supplémentaire n’est disponible, Next-Page est faux.
    Valeurs valides :
    • true : des données supplémentaires sont disponibles, un autre appel doit être effectué pour obtenir le bloc de données suivant.
    • false : aucune donnée supplémentaire.

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir une liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 6. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    404 Introuvable. L’élément demandé est introuvable.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres de corps de réponse (JSON ou XML)

    Élément Description
    Naissance Date de naissance de l’employé.

    Type de données : chaîne
    Société Nom de la société

    Type de données : chaîne
    E-mail Adresse e-mail de l’employé.

    Type de données : chaîne
    Identificateur de l’employé Identificateur unique d’employé.

    Type de données : chaîne
    Prénom Prénom de l’employé.

    Type de données : chaîne
    HireDate Date d’embauche de l’employé.

    Type de données : chaîne
    Lastname Nom de l’employé.

    Type de données : chaîne
    Deuxième prénom Deuxième prénom de l’employé.

    Type de données : chaîne
    Réembaucher Pour une utilisation future.

    Type de données : chaîne
    Adresse de résidence Adresse postale du domicile de l’employé.

    Type de données : chaîne
    Ville de résidence Ville du domicile de l’employé.

    Type de données : chaîne
    Pays de résidence Pays d’origine de l’employé.

    Type de données : chaîne
    RésidenceCode postal Code postal du domicile de l’employé.

    Type de données : chaîne
    État de résidence État du domicile de l’employé.

    Type de données : chaîne
    Suffixe Suffixe de l’employé, par exemple M., Mme ou Dr.

    Type de données : chaîne
    Adresse de travail Adresse postale du lieu de travail de l’employé.

    Type de données : chaîne
    Ville de travail Ville du lieu de travail de l’employé

    Type de données : chaîne
    Pays de travail Pays de travail de l’employé.

    Type de données : chaîne
    Code postal de travail Code postal professionnel de l’employé.

    Type de données : chaîne
    État de travail État du travail de l’employé.

    Type de données : chaîne

    Exemple de demande cURL pour les informations d’un employé spécifique

    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": ""
 }
]}

    Exemple de demande cURL pour une liste d’employés ajoutés/mis à jour à partir du 18/05/2019

    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": ""
  }
]}