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
timezone.name string
- Must be a valid Olson timezone
phone_number string
- Maximum 255 characters
locale.code string
- See Localization types
role_ids array
- role_ids.* integer
team_ids array
- team_ids.* integer
sso object
- Required without password
- sso.provider_user_id integer
- sso.provider_name string
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
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