Users - xpand-io/api-docs GitHub Wiki
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][email protected],[email protected]
GET /api/v1/users?filter[id]=56d0d9807661670f29080000,56d0d9807661670f29080001
Sample response
{
"data": [
{
"id": "56d0d9807661670f29080000",
"type": "users",
"attributes": {
"first_name": "Joe",
"last_name": "User",
"email": "[email protected]",
"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": "[email protected]",
"start_date": "2012-03-23"
}
}
]
}
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": "[email protected]",
"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"
Create a new user
Parameters for user object
Name | Required | Type | Notes | Validation messages |
---|---|---|---|---|
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]+$ |
|
|
work_email | String | Must be a valid email address. Must be unique for each user. |
|
|
first_name | required | String | Must not contain numbers or any of the following special characters !@#$%^&*() |
|
middle_name | String | Must not contain numbers or any of the following special characters !@#$%^&*() |
|
|
last_name | required | String | Must not contain numbers or any of the following special characters !@#$%^&*() |
|
legal_first_name | String | Must not contain numbers or any of the following special characters !@#$%^&*() |
|
|
legal_last_name | String | Must not contain numbers or any of the following special characters !@#$%^&*() |
|
|
start_date | required | String | Format: YYYY-MM-DD. Can be present, or future dates only. |
|
employee_type | required for offer_accepted candidates | String | See reference values here for allowed employee type values. |
|
candidate_status | required | String | See reference values here for allowed candidate status values. |
|
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. |
|
|
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) |
|
hris_id | String | This is the employee id of the Human Resource Information Systems (HRIS) |
|
|
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 |
|
external_ids | JSON | JSON where key is name of external service, e.g. {"ATS_ID": "123", "HRIS_ID": "abc"}
|
|
|
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) |
|
|
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) |
|
|
documents | Array | Array which holds the collection of document information, e.g.
|
|
|
educations | Array | Array which holds the collection of education information, e.g.
|
|
|
work_experiences | Array | Array which holds the collection of employment information, e.g.
|
|
|
addresses | Array | Array which holds the collection of address information, e.g.
|
|
|
phone_numbers | Array | Array which holds the collection of phone information, e.g.
|
|
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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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}
}
}'
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