Skip to content

Users

Jump to bottom
Abhilash S edited this page Feb 6, 2024 · 231 revisions

GET /api/v1/users

Get details for a multiple users.

Parameters

Name Required Notes
filter required can filter by id or email

Sample requests

GET /api/v1/users?filter[email]=jon@foo.bar,dave@foo.bar

GET /api/v1/users?filter[id]=56d0d9807661670f29080000,56d0d9807661670f29080001

Sample response

{
  "data": [
    {
      "id": "56d0d9807661670f29080000",
      "type": "users",
      "attributes": {
        "first_name": "Joe",
        "last_name": "User",
        "email": "joe.user@domain.com",
        "start_date": "2012-03-20",
        "external_ids": {
          "ATS_ID": "123",
          "HRIS_ID": "abc"
        }
      }
    }, {
      "id": "56d0d9807661670f29080001",
      "type": "users",
      "attributes": {
        "first_name": "Jen",
        "last_name": "User",
        "email": "jen.user@domain.com",
        "start_date": "2012-03-23"
      }
    }
  ]
}

GET /api/v1/users/:id

Get details for a single user. The id can be an Xpand ID, or an external ID in the format external_service=external_id, for example GET /api/v1/users/HRIS_ID=123456

Sample response

{
  "data": {
    "id": "56d0d9807661670f29080000",
    "type": "users",
    "attributes": {
      "first_name": "Joe",
      "last_name": "User",
      "email": "joe.user@domain.com",
      "start_date": "2012-03-20",
      "external_ids": {
        "ATS_ID": "123",
        "HRIS_ID": "abc"
      }
    }
  }
}

Sample cURL request

curl -i -H "Authorization: Token YOUR_API_KEY" -H "Content-Type: application/json" -X GET "https://subdomain.xpand.io/api/v1/users/55c6463369702d2181950000"

POST /api/v1/users

Create a new user

Parameters for user object

Name Required Type Notes Validation messages
email required String Must be a valid email address. Must be unique for each user. Non case-sensitive.
Regex validation: ^(?!...)[a-zA-Z0-9][\w-.]@[A-Za-z\d-]+(.[A-Za-z\d-]+)*.[A-Za-z]+$
  • Missing required params: email
  • Email address already exists
  • Email address invalid: joe@example
work_email String Must be a valid email address. Must be unique for each user.
  • Email address already exists
  • Email address invalid: joe@work-example
first_name required String Must not contain numbers or any of the following special characters !@#$%^&*()
  • Missing required params: first_name
  • First name has invalid characters
middle_name String Must not contain numbers or any of the following special characters !@#$%^&*()
  • Middle name has invalid characters
last_name required String Must not contain numbers or any of the following special characters !@#$%^&*()
  • Missing required params: last_name
  • Last name has invalid characters
legal_first_name String Must not contain numbers or any of the following special characters !@#$%^&*()
  • Legal first name has invalid characters
legal_last_name String Must not contain numbers or any of the following special characters !@#$%^&*()
  • Legal last name has invalid characters
start_date required String Format: YYYY-MM-DD. Can be present, or future dates only.
  • Missing required params: start_date
  • Invalid start date: 2020/25/01
  • Start date cannot be a past date
employee_type required for offer_accepted candidates String See reference values here for allowed employee type values.
  • Missing required params: employee_type
candidate_status required String See reference values here for allowed candidate status values.
  • Missing required params: candidate_status
legal_entity String See reference values here for existing legal entity values.
cost_center_id String See reference values here for existing cost center values.
relocation_type String
blocked Boolean Disable or enable a user account in Xpand.
  • Blocked can only be true or false
reason_blocked String A brief description of why the user why the user account is being disabled in Xpand
ats_id required String This is the unique id of the Applicant Tracking System (ATS)
  • Missing required params: ats_id
hris_id String This is the employee id of the Human Resource Information Systems (HRIS)
  • Missing required params: hris_id
office_location_id required JSON JSON where key is name of external service, e.g. `{"HRIS_ID": "NEWYORK". There must be an office location in Xpand with a matching employee id. See reference values here for existing office location external ids
  • Missing required params: office_location_id, Office location not found with ID: {"HRIS_ID"=>"54321"}
  • Office location not found for: {:office_location_id=>"111"}
external_ids JSON JSON where key is name of external service, e.g. {"ATS_ID": "123", "HRIS_ID": "abc"}
  • Missing required params: ATS_ID
recruiter_ids JSON JSON where key is name of external service, e.g. {:recruiter=>{"HRIS_SYS"=>"12345"}, recruiting_manager=>{"HRIS_SYS"=>"56789"}} (There must be a recruiter in Xpand or HRIS_SYS(Ex: workday) with a matching employee id)
  • Missing required params: recruiter
  • Missing required params: recruiting_coordinator
  • Recruiter not found with ID: {:recruiter=>{"HRIS_SYS"=>"12345"}}
user_manager_ids JSON JSON where key is name of external service, e.g. {:direct_manager=>{"HRIS_SYS"=>"12345"}, hiring_manager=>{"HRIS_SYS"=>"56789"}} (There must be a manager in Xpand or HRIS_SYS(Ex: workday) with a matching employee id)
  • Missing required params: manager
  • Missing required params: direct_manager
  • Manager not found with ID: {:manager=>{"HRIS_SYS"=>"12345"}}
documents Array Array which holds the collection of document information, e.g.
  • document_type (String)(Ex: offer_letter,resume,others)
  • document_number (String)
  • document_title (String)
  • document_position (Integer)
  • document_description (String)
  • issuer (String)
  • issuer_city (String)
  • issuer_state (String)
  • issuer_country (String)
  • issued_date (String)
  • expiry_date (String)
  • attachments (Array) [{file_name:'', file_content_base64:''}]
  • Missing required params: document_type
  • Invalid issue date: 2020/25/01
  • Expiry date cannot be a past date
  • Invalid document_type: Doc
educations Array Array which holds the collection of education information, e.g.
  • school_name (String)
  • degree (String)
  • start_date (String)
  • end_date (String)
  • student_id (String)
  • time_type (String)
  • major (String)
  • minor (String)
  • gpa (Float)
  • specialization (String)
  • graduated (Boolean)
  • graduation_date (String)
  • grade (String)
  • name_while_attending (String)
  • address (JSON){street:'', city:'', state:'', postal_code:'', country:''}
  • attachments (Array)[{file_name:'', file_content_base64:''}]
  • Missing required params: school_name, student_id, degree
  • Invalid start date: 2020/25/01
  • End date cannot be a prior to start date
work_experiences Array Array which holds the collection of employment information, e.g.
  • employer (String)
  • employee_id (String)
  • start_date (String)
  • end_date (String)
  • current (Boolean)
  • job_title (String)
  • department (String)
  • employment_type (String)
  • reason_for_leaving (String)
  • salary (String)
  • manager_name (String)
  • manager_phone (String)
  • manager_email (String)
  • hr_name (String)
  • hr_phone (String)
  • hr_email (String)
  • address (JSON){street:'', city:'', state:'', postal_code:'', country:''}
  • attachments (Array)[{file_name:'', file_content_base64:''}]
  • Missing required params: employer, employee_id
  • Invalid start date: 2020/25/01
  • End date cannot be a prior to start date
addresses Array Array which holds the collection of address information, e.g.
  • line_1 (String)
  • line_2 (String)
  • line_3 (String)
  • city (String)
  • state (String)
  • postal_code (String)
  • country (String)
  • current (Boolean)
  • permanent (Boolean)
  • start_date (String)
  • end_date (String)
  • attachments (Array)[{file_name:'', file_content_base64:''}]
  • Invalid country name/code: [country name]
phone_numbers Array Array which holds the collection of phone information, e.g.
  • number (String)(E.164 Format)
  • type (String)(Ex: mobile,landline,unknown)
  • primary (Boolean)
  • Missing required params: number, type, primary

Sample Input Offer Accepted

{
    "data": {
        "attributes": {
            "external_ids": {
                "ATS_ID": "test123",
                "HRIS_ID": null
            },
            "candidate_status": "offer_accepted",
            "first_name": "Joe",
            "last_name": "User",
            "email": "test123@xpand.io",
            "start_date": "2020-09-08",
            "legal_entity": "LE1",
            "cost_center_id": "CC1",
            "employee_type": "Intern",
            "blocked": false,
            "relocation_type": "none",
            "office_location_id": {
                "HRIS_ID": "NEWYORK"
            },
            "recruiter_ids": {
                "recruiter": {
                    "HRIS_SYS": "45678"
                },
                "recruiting_coordinator": {
                    "HRIS_SYS":"87654"
                },
                "recruiting_manager": {
                    "HRIS_SYS":"87654"
                }
            },
            "user_manager_ids": {
                "direct_manager": {
                    "HRIS_SYS":"87654"
                }
            },
            "educations": [
               {
                 "school_name": "string", /* College/ Institute/ University, Location */
                 "degree": "string", /* Course Name / Qualification/ Program Type */
                 "start_date": "string", /* Year Started */
                 "end_date": "string", /* Year of Passing */
                 "student_id": "string", /* Roll No/ Registration No/Enrollment No. */
                 "time_type": "string", /* Mode of Qualification/(Full Time/Part Time) */
                 "specialization": "string", /* Specialization */
                 "graduated": "boolean", /* Graduated */
                 "graduation_date": "string", /* Graduation Date */
                 "grade": "string", /* Grade */
                 "name_while_attending": "string", /* Name while attending the collage */
                 "major": "string",
                 "minor": "string",
                 "gpa": "float",
                 "address": {
                   "street": "string",
                   "city": "string",
                   "state": "string",
                   "postal_code": "string",
                   "country": "string"
                  },
                 "attachments": [
                   {
                     "file_name": "string", /* File Name. */
                     "file_content_base64": "string" /* Base 64 encoded string representation of the electronic file. */
                   }
                 ]
                }
             ],
            "work_experiences": [
                 {
                   "employer": "string", /* Company Name */
                   "employee_id": "string", /* Employee Code */
                   "start_date": "string", /* Year Started */
                   "end_date": "string", /* Year of Ended */
                   "current": "string", /* Current Employer */
                   "job_title": "string", /* Designation */
                   "department": "string", /* Department */
                   "employment_type": "string", /* Employment Type Regular/Contractor */
                   "reason_for_leaving": "string", /* Reason for Leaving */
                   "salary": "string", /* Salary */
                   "manager_name": "string", /* Manager Name */
                   "manager_phone": "string", /* Manager Phone */
                   "manager_email": "string", /* Manager Email */
                   "hr_name": "string", /* HR Name */
                   "hr_phone": "string", /* HR Phone */
                   "hr_email": "string", /* HR Email */
                   "address": {
                     "street": "string",
                     "city": "string",
                     "state": "string",
                     "postal_code": "string",
                     "country": "string"
                   },
                   "attachments": [
                    {
                      "file_name": "string", /* File Name. */
                      "file_content_base64": "string" /* Base 64 encoded string representation of the electronic file. */
                    }
                   ]
                 }
             ],
            "documents": [
                {
                    "document_type": "string", /* Type of document for the case eg. Passport, Driving Licence. Visa */
                    "document_number": "string", /* Identification number for the document eg. Passport number for a Passport. */
                    "document_title": "string", /* Title of the document. */
                    "document_position": "string", /* The order to be displayed to candidates. */
                    "document_description": "string", /* Description of the document. */
                    "issuer": "string", /* Issuing authority for the document. */
                    "issuer_city": "string", /* City which is the issuing authority of the document. */
                    "issuer_state": "string", /* State or Province which is the issuing authority of the document. */
                    "issuer_country": "string", /* Country which is the issuing authority of the document. */
                    "issued_date": "string", /* Date on which the document was issued. */
                    "expiry_date": "string", /* Expiry date of the document. */
                    "attachments": [
                        {
                            "file_name": "string", /* File Name. */
                            "file_content_base64": "string" /* Base 64 encoded string representation of the electronic file. */
                        }
                    ]
                }
            ],
            "addresses": [
              {
                "line_1": "31 St, 34 West",
                "line_2": "",
                "line_3": "",
                "city": "New York",
                "state": "New York",
                "postal_code": "10018",
                "country": "USA",
                "current": "true",
                "permanent": "false",
                "start_date": "2020-09-08",
                "end_date": "2023-09-08",
                "attachments": [
                 {
                   "file_name": "string", /* File Name. */
                   "file_content_base64": "string" /* Base 64 encoded string representation of the electronic file. */
                  }
                 ]
                }
            ],
           "phone_numbers": [
            {
               "number": "+14044580880",
               "type": "mobile",
               "primary": "true"
             },
             {
                "number": "+18559716364",
                "type": "landline",
                "primary": "false"
              }
            ],
            "position_data": {
              "job_family": "",
              "business_unit_id": "",
              "department": "",
              "position_type": "",
              "pay_rate": "",
              "job_title": "",
              "job_level": "",
              "cost_center_id": ""
             }
        }
    }
}

Sample Response

{
  "data": {
    "id": "5f7ba86ea51d9f356153c995",
    "type": "users",
    "attributes": {
        "created_at": "2020-10-05T23:12:46Z",
        "updated_at": "2020-10-05T23:12:46Z",
        "first_name": "Joe",
        "last_name": "User",
        "email": "test123@xpand.io",
        "start_date": "2020-09-08",
        "home_address": null,
        "external_ids": {
            "ATS_ID": "test123",
            "HRIS_ID": null
        },
        "badge_photo": null,
        "blocked": false,
        "reason_blocked": null,
        "candidate_status": "offer_accepted",
        "cost_center_id": "CC1",
        "job_profile_id": null,
        "relocation_type": "none",
        "legal_entity": "LE1",
        "recruiter_ids": {},
        "user_manager_ids": {}
    }
  }
}

Sample cURL request for Offer Accepted

curl -v -X POST https://domain-staging.xpand.io/api/v1/users -H "Content-Type: application/json" -H 'Accept: application/json' -H "Authorization: Token YOUR_API_KEY" -d '
{
"data": {
  "attributes": {
    "external_ids": {
      "ATS_ID": "test123", 
      "HRIS_ID": nil
    }, 
    "candidate_status": "pre_offer", 
    "first_name": "Joe", 
    "last_name": "User", 
    "email": "test123@xpand.io", 
    "start_date": "2100-01-01", 
    "legal_entity": "LE1", 
    "recruiter_ids": {
      "recruiter": {"HRIS_SYS": "012599"}, 
      "recruiting_coordinator": {"HRIS_SYS": "018004"}
      "recruiting_manager": {"HRIS_SYS": "018004"}
    }, 
    "manager_id": "direct_manager": {"HRIS_SYS": "012599"}, 
    "employee_type": "Regular", 
    "blocked": false}
  }
}'

PATCH /api/v1/users/:id

Update a user

Parameters for user object

Same as for create

Sample Input

Same as for create

Sample response

Same as for create

Sample cURL request

Same as for create

Clone this wiki locally