Individuals

Types

The Individual object

This object contains individual info info.

Field	Type	Description
IndividualId	int	Identifier created by NBS. Should not be provided for inserts.
NBSId	int	Unique identifier created by NBS. Should not be provided for inserts.
CompanyId	int	Readonly value. Should not be provided for inserts.
FirstName	string	Required
MiddleName	string
LastName	string	Required
EmployeeNumber	string	Must be unique within your entire company
SSN	string	Must be a valid 9-digit SSN. Required for clients using Verification Monitoring. The SSN field is only used for Insert/Update and is not returned when retrieving an individual or individual list.
UniqueNumber	string	Must be unique within your entire company
LogonId	string	Required. Must be unique within your entire company. Username may contain alpha numeric characters with a maximum length of 30 characters.
DateOfBirth	date	Required for clients using Verification Monitoring
HireDate	date
Gender	string	M or F or blank
JobTitleId	int	Ninth Brain’s internal unqiue id for the job title
JobTitle	string	See Job Title Resource
AdditionalJobTitles	List of JobTitles	This is readonly property, will not be used in inserts/updates.
Department	string	See Department Resource
Locale	string	See Locale Resource
BusinessUnitId	string	Identifer provided by company for locale. Note: Not enabled for all customers.
AdditionalLocales	List of Locales	Note: Additional Locales is not enabled for all customers. This is readonly property, will not be used in inserts/updates.
WorkShift	string	See WorkShift Resource
IsEmployee	int	1 for Yes. 0 for No.
IsSupervisor	int	1 for Yes. 0 for No. Default: 0 for inserts, keeps existing value if not provided for updates.
WorkStatus	String	See WorkStatus resource
Status	string	Required. Values are Active, LOA or Former.
SupervisorId	int	Links to Individual Resource to set Primary Supervisor
SupervisorName	string	Last/First Names of Primary Supervisor
PrimaryEmailAddress	string	Required. Must be a valid email address.
HomeAddressLine1	string	Required for clients using Verification Monitoring
HomeAddressLine2	string
HomeCity	string	Required for clients using Verification Monitoring
HomeState	string	Required for clients using Verification Monitoring
HomeCountry	string	Required for clients using Verification Monitoring
HomeZipCode	string	Required for clients using Verification Monitoring
HomePhoneNumber	string
BusinessPhoneNumber	string
MobilePhoneNumber	string
SendWelcomeLetter	bool	Default: false. Used when inserting individuals. If set to true, an Account Setup email will be sent to the user’s PrimaryEmailAddress
ExcludeFromVerificationMonitoring	bool	Default: false for inserts, keeps existing value if not provided for updates. Applicable only to clients using Verification Monitoring. If set to true, users can be insert without the requried fields for monitoring. This user will NOT be included in Verificate Monitoring

Endpoints

Get a List Of Individuals

Request

GET https://api.ninthbrain.com/Individual/GetList?api-version=2.0

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

[
  {
    "IndividualId": 0,
    "NBSId": 0,
    "FirstName": "",
    "MiddleName": "",
    "LastName": "",
    "EmployeeNumber": "",
    "UniqueNumber": "",
    "LogonId": "",
    "DateOfBirth": "1900-01-01",
    "Gender": "",
    "JobTitleId": 1234,
    "JobTitle": "",
    "AdditionalJobTitles": [
        {
          "JobTitleId": 123,
          "JobTitleName": "EMT"
        }
    ],
    "Department": "",
    "Locale": "",
    "WorkShift": "",
    "SupervisorId": 0,
    "Supervisor": "",
    "CompanyId": 0,
    "IsEmployee": 1,
    "IsSupervisor": 0,
    "WorkStatus": "",
    "Status": "",
    "HireDate": "1900-01-01",
    "PrimaryEmailAddress": "",
    "HomeAddressLine1": "",
    "HomeAddressLine2": "",
    "HomeCity": "",
    "HomeState": "",
    "HomeCountry": "",
    "HomeZipCode": "",
    "HomePhoneNumber": "",
    "BusinessPhoneNumber": "",
    "MobilePhoneNumber": ""
  }
]

Errors

not_found (HTTP 404) - individual does not exist
unauthorized (HTTP 401) - invalid credentials (bearer token) supplied
bad request (HTTP 400) - unknown error occurred

Get a List Of Supervisors

Request

GET https://api.ninthbrain.com/Individual/GetSupervisorList?api-version=2.0

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

[
  {
    "IndividualId": 0,
    "NBSId": 0,
    "FirstName": "",
    "MiddleName": "",
    "LastName": "",
    "DateOfBirth": "",
    "CompanyId": 0,
    "IsEmployee": 0,
    "IsSupervisor": 1,
    "Status": 30,
    "HireDate": "",
    "PrimaryEmailAddress": "",
    "HomePhoneNumber": "",
    "BusinessPhoneNumber": "",
    "MobilePhoneNumber": ""
  }
]

Errors

not_found (HTTP 404) - individual does not exist
unauthorized (HTTP 401) - invalid credentials (bearer token) supplied
bad request (HTTP 400) - unknown error occurred

Get a Individual By NBS Id

Request

GET https://api.ninthbrain.com/Individual/GetByNBSId?nbsId={nbsId}&api-version=2.0

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "IndividualId": 0,
  "NBSId": 0,
  "FirstName": "",
  "MiddleName": "",
  "LastName": "",
  "EmployeeNumber": "",
  "UniqueNumber": "",
  "LogonId": "",
  "DateOfBirth": "1900-01-01",
  "Gender": "",
  "JobTitle": "",
  "Department": "",
  "Locale": "",
  "WorkShift": "",
  "SupervisorId": 0,
  "Supervisor": "",
  "CompanyId": 0,
  "IsEmployee": 1,
  "IsSupervisor": 0,
  "WorkStatus": "",
  "Status": "",
  "HireDate": "1900-01-01",
  "PrimaryEmailAddress": "",
  "HomeAddressLine1": "",
  "HomeAddressLine2": "",
  "HomeCity": "",
  "HomeState": "",
  "HomeCountry": "",
  "HomeZipCode": "",
  "HomePhoneNumber": "",
  "BusinessPhoneNumber": "",
  "MobilePhoneNumber": ""
}

Errors

not_found (HTTP 404) - individual does not exist
unauthorized (HTTP 401) - invalid credentials (bearer token) supplied

Get a Individual By Unique Identifier

Request

GET https://api.ninthbrain.com/Individual/GetByUniqueIdentifier?uniqueIdentifier={uniqueIdentifier}&api-version=2.0

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "IndividualId": 0,
  "NBSId": 0,
  "FirstName": "",
  "MiddleName": "",
  "LastName": "",
  "EmployeeNumber": "",
  "UniqueNumber": "",
  "LogonId": "",
  "DateOfBirth": "1900-01-01",
  "Gender": "",
  "JobTitle": "",
  "Department": "",
  "Locale": "",
  "WorkShift": "",
  "SupervisorId": 0,
  "Supervisor": "",
  "CompanyId": 0,
  "IsEmployee": 1,
  "IsSupervisor": 0,
  "WorkStatus": "",
  "Status": "",
  "HireDate": "1900-01-01",
  "PrimaryEmailAddress": "",
  "HomeAddressLine1": "",
  "HomeAddressLine2": "",
  "HomeCity": "",
  "HomeState": "",
  "HomeCountry": "",
  "HomeZipCode": "",
  "HomePhoneNumber": "",
  "BusinessPhoneNumber": "",
  "MobilePhoneNumber": ""
}

Errors

not_found (HTTP 404) - individual does not exist
unauthorized (HTTP 401) - invalid credentials (bearer token) supplied
bad request (HTTP 400) - unknown error occurred
too_many_requests (HTTP 429) - API calls quota exceeded

Get a Individual By Employee Number

Request

GET https://api.ninthbrain.com/Individual/GetByEmployeeNumber?employeeNumber={employeeNumber}&api-version=2.0

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "IndividualId": 0,
  "NBSId": 0,
  "FirstName": "",
  "MiddleName": "",
  "LastName": "",
  "EmployeeNumber": "",
  "UniqueNumber": "",
  "LogonId": "",
  "DateOfBirth": "1900-01-01",
  "Gender": "",
  "JobTitle": "",
  "Department": "",
  "Locale": "",
  "WorkShift": "",
  "SupervisorId": 0,
  "Supervisor": "",
  "CompanyId": 0,
  "IsEmployee": 1,
  "IsSupervisor": 0,
  "WorkStatus": "",
  "Status": "",
  "HireDate": "1900-01-01",
  "PrimaryEmailAddress": "",
  "HomeAddressLine1": "",
  "HomeAddressLine2": "",
  "HomeCity": "",
  "HomeState": "",
  "HomeCountry": "",
  "HomeZipCode": "",
  "HomePhoneNumber": "",
  "BusinessPhoneNumber": "",
  "MobilePhoneNumber": ""
}

Errors

not_found (HTTP 404) - individual does not exist
unauthorized (HTTP 401) - invalid credentials (bearer token) supplied
bad request (HTTP 400) - unknown error occurred

Check if an Individual Exists

Checks if an employee with the provided unique identifier exists and returns simple true or false.

Request

GET https://api.ninthbrain.com/Individual/Exists?uniqueIdentifier={uniqueIdentifier}&api-version=2.0

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

true

Errors

unauthorized (HTTP 401) - invalid credentials (bearer token) supplied
bad request (HTTP 400) - unknown error occurred
too_many_requests (HTTP 429) - API calls quota exceeded

Insert Individual

Request

POST https://api.ninthbrain.com/Individual/Insert?api-version=2.0

Request Body

{
    "FirstName": "John",
    "MiddleName": "",
    "LastName": "Doe",
    "EmployeeNumber": "123",
    "UniqueNumber": "1234",
    "LogonId": "jdoe",
    "Gender": "Male",
    "JobTitle": "Sample Job",
    "Department": "Sample Department",
    "Locale": "Sample District",
    "WorkShift": "Full Time",
    "SupervisorId": 12345,
    "Supervisor": "Sample Supervisor",
    "IsEmployee": 1,
    "IsSupervisor": 1,
    "WorkStatus": "Full Time",
    "Status": "Active",
    "HireDate": "2020-09-01T00:00:00-04:00",
    "PrimaryEmailAddress": "sample@example.com",
    "HomeAddressLine1": "123 Anywhere",
    "HomeAddressLine2": "",
    "HomeCity": "Anytown",
    "HomeState": "MI",
    "HomeZipCode": "12345",
    "HomePhoneNumber": "",
    "BusinessPhoneNumber": "",
    "MobilePhoneNumber": "123-123-1234",
    "ExcludeFromVerificationMonitoring": False
}

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8

{
    "IndividualId": 1234,
    "NBSId": 1234,
    "FirstName": "John",
    "MiddleName": "",
    "LastName": "Doe",
    "EmployeeNumber": "123",
    "UniqueNumber": "1234",
    "LogonId": "jdoe",
    "Gender": "Male",
    "JobTitle": "Sample Job",
    "Department": "Sample Department",
    "Locale": "Sample District",
    "WorkShift": "Full Time",
    "SupervisorId": 12345,
    "Supervisor": "Sample Supervisor",
    "IsEmployee": 1,
    "IsSupervisor": 1,
    "WorkStatus": "Full Time",
    "Status": "Active",
    "HireDate": "2020-09-01T00:00:00-04:00",
    "PrimaryEmailAddress": "sample@example.com",
    "HomeAddressLine1": "123 Anywhere",
    "HomeAddressLine2": "",
    "HomeCity": "Anytown",
    "HomeState": "MI",
    "HomeZipCode": "12345",
    "HomePhoneNumber": "",
    "BusinessPhoneNumber": "",
    "MobilePhoneNumber": "123-123-1234",
    "ExcludeFromVerificationMonitoring": False
}

Errors

unauthorized (HTTP 401) - invalid credentials (bearer token) supplied
not_modified (HTTP 304) - error occurred
bad request (HTTP 400) - unknown error occurred

Update Individual

Updates an indivdual in Ninth Brain. While you can construct the request from scratch, a more reliable workflow is to get the current indivdual using an existing endpoint such as ‘GetByEmployeeNumber’, ‘GetByUniqueIdentifier’, or ‘GetByNBSId’, update as needed and then post to the Update endpoint. This is will ensure only the fields you expect change.

Request

POST https://api.ninthbrain.com/Individual/Update?api-version=2.0

Request Body

{
    "NBSId": 1234,
    "FirstName": "John",
    "MiddleName": "",
    "LastName": "Doe",
    "EmployeeNumber": "123",
    "UniqueNumber": "1234",
    "LogonId": "jdoe",
    "Gender": "Male",
    "JobTitle": "Sample Job",
    "Department": "Sample Department",
    "Locale": "Sample District",
    "WorkShift": "Full Time",
    "SupervisorId": 12345,
    "Supervisor": "Sample Supervisor",
    "CompanyId": 1234,
    "IsEmployee": 1,
    "IsSupervisor": 1,
    "WorkStatus": "Full Time",
    "Status": "Active",
    "HireDate": "2020-09-01T00:00:00-04:00",
    "PrimaryEmailAddress": "sample@example.com",
    "HomeAddressLine1": "123 Anywhere",
    "HomeAddressLine2": "",
    "HomeCity": "Anytown",
    "HomeState": "MI",
    "HomeZipCode": "12345",
    "HomePhoneNumber": "",
    "BusinessPhoneNumber": "",
    "MobilePhoneNumber": "123-123-1234",
    "ExcludeFromVerificationMonitoring": False
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
    "IndividualId": 1234,
    "NBSId": 1234,
    "FirstName": "John",
    "MiddleName": "",
    "LastName": "Doe",
    "EmployeeNumber": "123",
    "UniqueNumber": "1234",
    "LogonId": "jdoe",
    "Gender": "Male",
    "JobTitle": "Sample Job",
    "Department": "Sample Department",
    "Locale": "Sample District",
    "WorkShift": "Full Time",
    "SupervisorId": 12345,
    "Supervisor": "Sample Supervisor",
    "CompanyId": 1234,
    "IsEmployee": 1,
    "IsSupervisor": 1,
    "WorkStatus": "Full Time",
    "Status": "Active",
    "HireDate": "2020-09-01T00:00:00-04:00",
    "PrimaryEmailAddress": "sample@example.com",
    "HomeAddressLine1": "123 Anywhere",
    "HomeAddressLine2": "",
    "HomeCity": "Anytown",
    "HomeState": "MI",
    "HomeZipCode": "12345",
    "HomePhoneNumber": "",
    "BusinessPhoneNumber": "",
    "MobilePhoneNumber": "123-123-1234",
    "ExcludeFromVerificationMonitoring": False
}

Errors

unauthorized (HTTP 401) - invalid credentials (bearer token) supplied
not_modified (HTTP 304) - error occurred
bad request (HTTP 400) - unknown error occurred