Users
A user is always connected to an company-account, which is represented in your endpoint.
A user can also be part of multiple teams, and switch between them. When switching between teams, the team that's being switched to is marked as the default team. When fetching a user through, for example, the /companies/:company_id/users endpoint, that team will be the users' default team.
Creating a user
POST /companies/:company_id/users
Creating a user with an token
POST /companies/:company_id/users/:invite_token
Creates a user for the specified company, using an invite token (available to clients; doesn't require user authentication)
Creating a user with SSO
If you have a trusted client, and EASI'R has created an SSO driver for your company, you can create a user for SSO authentication.
Parameters
email
string- Required
- Must be a valid email
- Must be unique
- Maximum 100 characters
first_name
string- Required
- Maximum 255 characters
last_name
string- Required
- Maximum 255 characters
job_title
string- Maximum 255 characters
password
string- Required without
sso
- Minimum 10 characters
- Required without
timezone.name
string- Must be a valid Olson timezone
phone_number
string- Maximum 255 characters
locale.code
stringrole_ids
arrayrole_ids.*
integer
team_ids
arrayteam_ids.*
integer
sso
object- Required without
password
sso.provider_user_id
integersso.provider_name
string
- Required without
system_user
boolean - Mark the user as system user.
Payload
{
"first_name": "Another",
"last_name": "Doe",
"phone_number": "+44123 456",
"job_title": "Animal",
"email": "another_email@example.com",
"timezone": {
"name": "Europe/Berlin"
},
"locale": {
"code": "de-DE"
},
"password": "very_very_secret",
"role_ids": null,
"team_ids": [1, 2],
"sso": null,
"system_user": false
}
Response
Status code 201
{
"id": 103,
"first_name": "Another",
"last_name": "Doe",
"phone_number": "+44123 456",
"formatted_phone_number": "+44123 456",
"job_title": "Animal",
"email": "another_email@example.com",
"email_notifications": false,
"profile_picture": null,
"locale": {
"code": "de-DE",
"language_name": "German",
"country": {
"name": "Germany",
"native_name": "Deutschland",
"code": "DE"
}
},
"timezone": {
"name": "Europe\/Berlin",
"offset": 7200
},
"team": {
"id": 1,
"name": "Team 1",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"team_type": null,
"group_id": 1,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
},
"teams": [
{
"id": 1,
"name": "Team 1",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"team_type": null,
"group_id": 1,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
},
{
"id": 2,
"name": "Team 2",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"team_type": null,
"group_id": 1,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
}
],
"system_user": false,
"created_at": "2017-05-10 13:20:12",
"updated_at": "2017-05-10 13:20:12"
}
Get list of users in a company
GET /companies/:company_id/users
Query string parameters
- Supports Searching
- Supports Pagination
ids
integer - Only show users with these ids (comma separated)
Response
Status code 200
{
"data": [
{
"id": 1,
"first_name": "Doe",
"last_name": "John",
"phone_number": "+4588888888",
"formatted_phone_number": "+4588888888",
"job_title": "Animal",
"email": "info@easir.com",
"profile_picture": "http://cdn.cutestpaw.com/wp-content/uploads/2013/06/l-Baby.jpeg",
"locale": {
"code": "de-DE",
"language_name": "German",
"country": {
"name": "Germany",
"native_name": "Deutschland",
"code": "DE"
}
},
"timezone": {
"name": "Europe/Copenhagen",
"offset": 3600
},
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
}
],
"pagination": {
"total": 10,
"page": 0,
"per_page": 15,
"urls": {
"previous": null,
"next": null
}
}
}
Get a specific user
GET /companies/:company_id/users/:user_id
Note: The team
relation will be the users' default team (e.g. the team that the user last switched to).
Response
Status code 200
{
"id": 1,
"first_name": "Doe",
"last_name": "John",
"phone_number": "+4588888888",
"formatted_phone_number": "+4588888888",
"job_title": "Animal",
"email": "info@easir.com",
"profile_picture": "http://api.randomuser.me/portraits/thumb/women/5.jpg",
"user_type": {
"id": 1,
"name": "admin"
},
"locale": {
"code": "en-US",
"language_name": "English",
"country": {
"name": "United States",
"native_name": "United States",
"code": "US"
}
},
"timezone": {
"name": "Europe/Copenhagen",
"offset": 3600
},
"signature": {
"email": "Some email signature"
},
"team": {
"id": 1,
"name": "Team 1",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
},
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
}
Updating a user
PUT /companies/:company_id/users/:user_id
Parameters
- Uses same paramaters as Create a user
user_type.id
integer- Must be a valid user type:
- Admin:
1
- Team Admin:
2
- User:
3
- Group Admin:
5
- Admin:
- Must be a valid user type:
signature.email
string- Maximum characters 65535
Payload
{
"first_name": "Another",
"last_name": "Doe",
"phone_number": "+44123 456",
"job_title": "Animal",
"email": "info@easir.com",
"timezone": {
"name": "Europe/Berlin"
},
"locale": {
"code": "de-DE"
},
"signature": {
"email": "Some email signature"
},
"email_notifications": true,
"role_ids": [2, 3],
"team_ids": [4, 5],
"user_type": {
"id": 3
}
}
Response
Status code 200
{
"id": 1,
"first_name": "Another",
"last_name": "Doe",
"phone_number": "+44123 456",
"formatted_phone_number": "+44123456",
"job_title": "Animal",
"email": "info@easir.com",
"profile_picture": "http://cdn.cutestpaw.com/wp-content/uploads/2013/06/l-Baby.jpeg",
"locale": {
"code": "en-US",
"language_name": "English",
"country": {
"name": "United States",
"native_name": "United States",
"code": "US"
}
},
"timezone": {
"name": "Europe/London",
"offset": 0
},
"signature": {
"email": "Some email signature"
},
"email_notifications": true,
"team": {
"id": 4,
"name": "Team 4",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"group": {
"id": 2,
"name": "Group 2",
"teams": [
{
"id": 3,
"name": "Team 3",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"team_type": null,
"group_id": 2,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
},
{
"id": 4,
"name": "Team 4",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"team_type": null,
"group_id": 2,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
}
],
"created_at": "2016-10-12 09:42:46",
"updated_at": "2016-10-12 09:42:46"
},
"team_type": null,
"group_id": 2,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
},
"roles": [
{
"id": 2,
"name": "Role 2",
"created_at": "2014-01-01 12:45:56",
"deleted_at": "2014-01-02 00:11:22"
},
{
"id": 3,
"name": "Role 3",
"created_at": "2014-01-01 12:45:56",
"deleted_at": "2014-01-02 00:11:22"
}
],
"teams": [
{
"id": 4,
"name": "Team 4",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"team_type": null,
"group_id": 2,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
},
{
"id": 5,
"name": "Team 5",
"address_1": "Savannah 123",
"address_2": "Under the tree on the left",
"zip_code": "4730",
"city": "Umzimkulu",
"state": "KwaZulu-Natal",
"country": null,
"phone_number": "031 308 7900",
"website": "https://easir.com",
"vat": "1234567890123456",
"team_type": null,
"group_id": null,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2014-01-02 00:11:22"
}
],
"created_at": "2014-01-01 12:45:56",
"updated_at": "2015-02-24 07:42:20"
}
Updating user profile picture
POST /users/:user_id/profile-picture
Headers
Content-Type: multipart/form-data
Parameters
profile_picture
file- Required
- Allowed files (jpg, png, gif, svg)
- File size maximum 2 megabytes
Response
Status code 200
{
"profile_picture": "http://cdn.cutestpaw.com/wp-content/uploads/2013/06/l-Baby.jpeg"
}
Deleting a user
DELETE /companies/:company_id/users/:user_id
Query string parameters
assign_to
integer - If the user has any open cases/tasks, they will be reassigned to the specified user.
Response
Status code 204
Change user password
PUT /companies/:company_id/users/:user_id/password
Update password
Parameters
old_password
string- Required
new_password
string- Required
Payload
{
"old_password": "password",
"new_password": "new_password"
}
Response
Status code 200
{
"id": 1,
"first_name": "Another",
"last_name": "Doe",
"phone_number": "+44123 456",
"formatted_phone_number": "+44123456",
"job_title": "Animal",
"email": "info@easir.com",
"profile_picture": "http://cdn.cutestpaw.com/wp-content/uploads/2013/06/l-Baby.jpeg",
"locale": {
"code": "en-US",
"language_name": "English",
"country": {
"name": "United States",
"native_name": "United States",
"code": "US"
}
},
"timezone": {
"name": "Europe/London",
"offset": 0
},
"created_at": "2014-01-01 12:45:56",
"updated_at": "2015-02-24 07:44:51"
}
Forgot password
POST /reset-password
This function can only be used by trusted clients.
Parameters
email
string- Required
- Must be a valid email
Payload
{
"email": "example@example.com"
}
Response
Status code 204
If no user is found, it will still return Status code 204.
Verify forgotten password
POST /reset-password/verify/:token
Parameters
password
string- Required
- Minimum 10 characters
Payload
{
"password": "i£Like&turtles12345678"
}
Response
Status code 200
{
"email": "example@example.com"
}
List user teams
GET /companies/:companyId/users/:userId/teams
Response
Status code 200
{
"data": [
{
"id": 238,
"name": "Sales team London",
"address_1": null,
"address_2": null,
"zip_code": null,
"city": null,
"state": null,
"country": null,
"phone_number": null,
"formatted_phone_number": null,
"website": null,
"vat": null,
"timezone": {
"name": "Europe/London",
"offset": 3600
},
"locale": {
"code": "en-GB",
"language_name": "English",
"country": {
"name": "United Kingdom",
"native_name": "United Kingdom",
"code": "GB"
}
},
"team_type": null,
"group_id": 1,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2016-09-09 12:53:45"
},
{
"id": 34,
"name": "Sales team Manchester",
"address_1": null,
"address_2": null,
"zip_code": null,
"city": null,
"state": null,
"country": null,
"phone_number": null,
"formatted_phone_number": null,
"website": null,
"vat": null,
"timezone": {
"name": "Europe/London",
"offset": 3600
},
"locale": {
"code": "en-GB",
"language_name": "English",
"country": {
"name": "United Kingdom",
"native_name": "United Kingdom",
"code": "GB"
}
},
"team_type": null,
"group_id": 1,
"use_social_lookup": false,
"created_at": "2014-01-01 12:45:56",
"updated_at": "2016-09-09 12:53:45"
}
]
}
Switch team
PUT /switch-team
A user can be part of multiple teams, however, only a single team can be used at a time.
When switching teams, the team that is being switched to will be marked as default.
In the next request, the user will belong to the default team until the team is switched again.
Parameters
team_id
integer
Payload
{
"team_id": 378
}
Response
Status code 204