HR REST API

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 4 Minuten Lesedauer

    • Die HR-REST -API stellt Endpunkte bereit, die Informationen zu Mitarbeitern zurückgeben, die in den USA arbeiten oder leben.

    Für den Zugriff auf diese API müssen Sie die Rolle sn_hr_core.USA_employee_only und das Plugin Human Resources Scoped App: Core (com_sn_hr_core) aktivieren.

    HR REST: GET /get_USA_employee_profile

    Gibt Mitarbeiterprofilinformationen für Mitarbeiter mit Sitz in den USA zurück.

    Die zurückgegebenen Informationen können entweder sein:
    • Mitarbeiterprofilinformationen für eine angegebene Mitarbeiter-ID.
    • Informationen für Mitarbeiter, die an oder nach einem bestimmten Datum hinzugefügt wurden oder deren Informationen aktualisiert wurden.
    Hinweis:
    Mitarbeiter müssen entweder als Arbeits- oder Heimatland als „Vereinigte Staaten“ angegeben haben, damit dieser Endpunkt sie in die zurückgegebenen Ergebnisse einbezieht.
    Darüber hinaus sendet der Endpunkt die folgenden Parameter an die integrierte Anwendung CIC Plus (Beschreibungen finden Sie im Abschnitt „Rückgaben“):
    • Mitarbeiterbezeichner
    • Vorname
    • Mittelname
    • Nachname
    • E-Mail
    • WorkAddress
    • WorkStadt
    • Arbeitsstatus
    • WorkPostalCode
    • WorkCountry
    • HomeAddress
    • Heimatstadt
    • Heimatstatus
    • HomePostalCode
    • Heimatland
    • Geburtsdatum
    • Einstellungsdatum

    URL-Format

    Standard-URL: /api/sn_hr_core/hr_rest_api/get_USA_employee_profile

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    Keine
    Tabelle : 2. Abfrageparameter
    Parameter Beschreibung
    employee_identifier Eindeutiger Bezeichner eines Mitarbeiters Das aufrufende System generiert diesen Wert und kann jedes Format aufweisen, das mit dem System konsistent ist. Um diesen Wert zu erhalten, rufen Sie zuerst den Endpunkt mit dem Parameter updated_after auf.
    Hinweis:
    Dieser Parameter und der Parameter updated_after schließen sich gegenseitig aus. Dieser Parameter definiert einen eindeutigen Mitarbeiter, während updated_after eine Gruppe von Mitarbeitern zurückgibt, die nach einem bestimmten Datum erstellt/aktualisiert wurden.

    Datentyp: Zeichenfolge
    sysparm_limit Maximale Anzahl der zurückzugebenden Datensätze. Verwenden Sie für Anforderungen, die diese Anzahl von Datensätzen überschreiten, den Parameter sysparm_offset, um den Datensatzabruf zu paginieren.

    Datentyp: Zahl

    Standardwert: 1000
    sysparm_offset Startdatensatzindex, für den der Datensatz abgerufen werden soll. Verwenden Sie diesen Wert, um den Datensatzabruf zu paginieren. Diese Funktion ermöglicht das Abrufen aller Datensätze in kleinen, verwaltbaren Abschnitten, unabhängig von der Anzahl der Datensätze.

    Wenn zum Beispiel dieser Endpunkt zum ersten Mal aufgerufen wird, ist sysparm_offset auf „0“ eingestellt. Verwenden Sie sysparm_offset=sysparm_offset+sysparm_limit zum einfachen Durchblättern aller verfügbaren Datensätze, bis das Ende aller Datensätze erreicht ist.
    updated_after Datum, das zur Bestimmung der zurückzugebenden Mitarbeiterdaten verwendet wird. Alle in den USA ansässigen Mitarbeiter (Arbeit oder Privat), die Ihrer Instanz hinzugefügt wurden oder deren Informationen an oder nach diesem Datum aktualisiert wurden, sind in den zurückgegebenen Ergebnissen enthalten.
    Hinweis:
    Dieser Parameter und der Parameter employee_identifier schließen sich gegenseitig aus.

    Datentyp: Zeichenfolge

    Format: JJJJ-MM-TT HH:MM:SS oder JJJJ-MM-TT (Standardeinstellung für Uhrzeit: 00:00:00)
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    Keine

    Kopfzeilen

    Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 5. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Nächste Seite Kennzeichnung, die angibt, ob in einem nachfolgenden Aufruf zusätzliche Daten abzurufen sind. Wenn beispielsweise insgesamt 120 Mitarbeiterdatensätze den Suchkriterien entsprechen und „sysparm_limit“ auf 100 festgelegt ist, ist Next-Page „wahr“. Wenn keine zusätzlichen Ergebnisse verfügbar sind, ist Next-Page gleich „falsch“.
    Gültige Werte:
    • „wahr“: Zusätzliche Daten sind verfügbar. Es muss ein weiterer Aufruf erfolgen, um den nächsten Datenblock zu erhalten.
    • „falsch“: Keine zusätzlichen Daten.

    Statuscodes

    Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    404 Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Parameter des Antworttexts (JSON oder XML)

    Element Beschreibung
    Geburtsdatum Geburtsdatum des Mitarbeiters.

    Datentyp: Zeichenfolge
    Unternehmen Unternehmensname.

    Datentyp: Zeichenfolge
    E-Mail E-Mail-Adresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    Mitarbeiterbezeichner Eindeutiger Bezeichner des Mitarbeiters.

    Datentyp: Zeichenfolge
    Vorname Vorname des Mitarbeiters

    Datentyp: Zeichenfolge
    Einstellungsdatum Datum, an dem der Mitarbeiter eingestellt wurde.

    Datentyp: Zeichenfolge
    Nachname Nachname des Mitarbeiters

    Datentyp: Zeichenfolge
    Mittelname Zweiter Vorname des Mitarbeiters.

    Datentyp: Zeichenfolge
    Wiedereinstellen Zur späteren Verwendung.

    Datentyp: Zeichenfolge
    Wohnsitzadresse Privatadresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    WohnsitzStadt Heimatort des Mitarbeiters.

    Datentyp: Zeichenfolge
    WohnsitzLand Heimatland des Mitarbeiters.

    Datentyp: Zeichenfolge
    Postleitzahl des Wohnsitzes Privatpostleitzahl des Mitarbeiters.

    Datentyp: Zeichenfolge
    Wohnsitzstatus Heimatstatus des Mitarbeiters.

    Datentyp: Zeichenfolge
    Suffix Namenszusatz des Mitarbeiters, z. B. Mr., Mrs. oder Dr.

    Datentyp: Zeichenfolge
    WorkAddress Berufliche Adresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    WorkStadt Arbeitsort des Mitarbeiters

    Datentyp: Zeichenfolge
    WorkCountry Arbeitsland des Mitarbeiters.

    Datentyp: Zeichenfolge
    WorkPostalCode Arbeitspostleitzahl des Mitarbeiters.

    Datentyp: Zeichenfolge
    Arbeitsstatus Arbeitsstatus des Mitarbeiters.

    Datentyp: Zeichenfolge

    Beispiel für eine cURL-Anforderung für die Informationen eines bestimmten Mitarbeiters

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

    Beispiel für eine cURL-Anforderung für eine Liste von Mitarbeitern, die am oder nach dem 18.05.2019 hinzugefügt/aktualisiert wurden

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