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
  • phone_number string
    • Maximum 255 characters
  • locale.code string
  • 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