API REST RH

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 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, vous devez avoir le rôle sn_hr_core.usa_employee_only et le module d’extension Human Resources Scoped App : Core (com_sn_hr_core) activé.

    REST RH : OBTENIR /get_usa_employee_profile

    Renvoie les informations de profil de l’employé pour les employés basés aux États-Unis.

    Les informations renvoyées peuvent être soit :
    • Informations de profil de l’employé pour un ID d’employé spécifié.
    • Informations relatives aux employés qui ont été ajoutés ou dont les informations ont été mises à jour à une date spécifiée ou après cette date.
    Remarque :
    Les employés doivent avoir spécifié leur pays de travail ou de résidence comme étant les États-Unis pour que ce point de terminaison les inclue dans les résultats de retour.
    De plus, le point de terminaison envoie les paramètres suivants à l’application CIC Plus intégrée (voir la section Déclarations pour les descriptions) :
    • Identificateur d’employé
    • Prénom
    • Deuxième prénom
    • Nom de famille
    • E-mail
    • Adresse de travail
    • WorkCity
    • État du travail
    • Code postal du travail
    • Pays du travail
    • Adresse du domicile
    • Ville d’origine
    • État d’origine
    • AccueilCode postal
    • Pays d’origine
    • Naissance
    • Date d’embauche

    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 d’appel 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 s’exclut mutuellement 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

    Valeur 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é à retourner. 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 à cette date ou après cette date, sont inclus dans les résultats de retour.
    Remarque :
    Ce paramètre s’exclut mutuellement avec le employee_identifier paramètre.

    Type de données : chaîne

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

    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 la 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, s’il existe un total de 120 enregistrements d’employés qui 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 :
    • vrai : des données supplémentaires sont disponibles, un autre appel doit être effectué pour obtenir le bloc de données suivant.
    • faux : aucune donnée supplémentaire.

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la 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 du corps de la 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 d’employé Identificateur unique de l’employé.

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

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

    Type de données : chaîne
    Nom de famille Nom de famille 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 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
    Code postal de résidence 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é, tel que M., Mme ou Dr.

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

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

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

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

    Type de données : chaîne
    État du travail État de 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 des employés ajoutés/mis à jour le 18/05/2019 ou après

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