HR-REST-API

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 4 Minuten Lesedauer

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

    Um auf diese API zuzugreifen, müssen Sie die Rolle sn_hr_core.usa_employee_only und das Plugin Human Resources Scoped App: Core (com_sn_HR_Core) aktiviert haben.

    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:
    • Mitarbeiterprofilinformationen für eine angegebene Mitarbeiter-ID.
    • Informationen für Mitarbeiter, die am oder nach einem bestimmten Datum hinzugefügt oder deren Informationen aktualisiert wurden.
    Hinweis:
    Mitarbeiter müssen entweder ihr Arbeits- oder Heimatland als USA angegeben haben, damit dieser Endpunkt sie in die Rückgabeergebnisse einbezieht.
    Darüber hinaus sendet der Endpunkt die folgenden Parameter an die integrierte CIC Plus-Anwendung (Beschreibungen finden Sie im Abschnitt „Rückgaben“):
    • EmployeeIdentifier
    • Vorname
    • MiddleName
    • Nachname
    • E-Mail
    • WorkAddress
    • WorkCity
    • Arbeitsstatus
    • Postleitzahl des Arbeitsbereichs
    • ArbeitsCountry
    • Privatadresse
    • Heimatstadt
    • HomeState
    • HomePostleitzahl
    • Homecountry
    • Geburtsdatum
    • Eingestellt

    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 in jedem Format vorliegen, das mit seinem System konsistent ist. Um diesen Wert zu erhalten, rufen Sie zuerst den Endpunkt mit auf updated_afterParameter.
    Hinweis:
    Dieser Parameter schließt sich gegenseitig mit aus updated_afterParameter. Dieser Parameter definiert einen eindeutigen Mitarbeiter, wobei updated_afterGibt eine Gruppe von Mitarbeitern zurück, die nach einem angegebenen 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 werden soll. Alle in den USA ansässigen Mitarbeiter (beruflich oder privat), die Ihrer Instanz hinzugefügt wurden oder deren Informationen am oder nach diesem Datum aktualisiert wurden, werden in die Rückgabeergebnisse aufgenommen.
    Hinweis:
    Dieser Parameter schließt sich gegenseitig mit aus employee_identifierParameter.

    Datentyp: Zeichenfolge

    Format: JJJJ-MM-TT HH:MM:SS oder JJJJ-MM-TT (Zeit standardmäßig 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 bei einem nachfolgenden Anruf zusätzliche Daten abgerufen werden sollen. Wenn beispielsweise insgesamt 120 Mitarbeiterdatensätze vorhanden sind, die den Suchkriterien entsprechen, und sysparm_limit auf 100 festgelegt ist, dann Next-PageIst „wahr“. Wenn keine zusätzlichen Ergebnisse verfügbar sind, Next-PageIst „falsch“.
    Gültige Werte:
    • Wahr: Zusätzliche Daten sind verfügbar. Ein weiterer Aufruf muss erfolgen, um den nächsten Datenblock abzurufen.
    • 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 REST API-HTTP-Antwortcodes .

    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.

    Antworttext-Parameter (JSON oder XML)

    Element Beschreibung
    Geburtsdatum Geburtsdatum des Mitarbeiters.

    Datentyp: Zeichenfolge
    Unternehmen Unternehmensname.

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

    Datentyp: Zeichenfolge
    EmployeeIdentifier Eindeutiger Mitarbeiterbezeichner.

    Datentyp: Zeichenfolge
    Vorname Vorname des Mitarbeiters

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

    Datentyp: Zeichenfolge
    Nachname Nachname des Mitarbeiters

    Datentyp: Zeichenfolge
    MiddleName Zweiter Vorname des Mitarbeiters.

    Datentyp: Zeichenfolge
    Wiedereinstellung Zur zukünftigen Verwendung.

    Datentyp: Zeichenfolge
    ResidenceAddress Privatadresse des Mitarbeiters.

    Datentyp: Zeichenfolge
    ResidenceCity Heimatort des Mitarbeiters.

    Datentyp: Zeichenfolge
    WohnsitzCountry Heimatland des Mitarbeiters.

    Datentyp: Zeichenfolge
    ResidencePostleitzahl Postleitzahl (privat) des Mitarbeiters.

    Datentyp: Zeichenfolge
    ResidenceStatus Privatstatus des Mitarbeiters.

    Datentyp: Zeichenfolge
    Suffix Suffix des Mitarbeiters, z. B. Herr, Frau oder Dr.

    Datentyp: Zeichenfolge
    WorkAddress Straße und Hausnummer des Mitarbeiters.

    Datentyp: Zeichenfolge
    WorkCity Arbeitsort des Mitarbeiters

    Datentyp: Zeichenfolge
    ArbeitsCountry Arbeitsland des Mitarbeiters.

    Datentyp: Zeichenfolge
    Postleitzahl des Arbeitsbereichs Postleitzahl der Arbeit 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 der Mitarbeiter, die am oder nach dem 18/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": ""
  }
]}