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