User

These endpoints allow the retrieval of users on this account and their preferences such as local time zone, default currency, language and date format. They can also be used to update user preferences, such as the click to call preference. For a full description of the user model see User model definition.

List Users

List all the users on this Capsule account.

GET
https://api.capsulecrm.com/api/v2/users

Query Parameters

Name Type Description
embed Array of String

Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Can be empty or party.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property users which is an array of User objects. In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200
{
  "users" : [ {
    "id" : 1,
    "locale" : "en_GB",
    "currency" : "EUR",
    "status" : "ACTIVE",
    "emailPreference" : null,
    "clickToCallPreference" : null,
    "preferredEmailFromAddress" : null,
    "party" : {
      "id" : 1,
      "type" : "person",
      "firstName" : "Scott",
      "lastName" : "Spacey",
      "pictureURL" : "https://facehub.appspot.com/default/person?text=SS&size=100"
    },
    "username" : "scott",
    "timezone" : "Europe/London",
    "lastLoginAt" : "2015-12-11T14:01:15Z",
    "name" : "Scott Spacey",
    "taskReminder" : true
  }, {
    "id" : 12345682,
    "locale" : "en_GB",
    "currency" : "GBP",
    "status" : "ACTIVE",
    "emailPreference" : null,
    "clickToCallPreference" : null,
    "preferredEmailFromAddress" : null,
    "party" : {
      "id" : 448488,
      "type" : "person",
      "firstName" : "John",
      "lastName" : "Spacey",
      "pictureURL" : "https://facehub.appspot.com/default/person?text=JS&size=100"
    },
    "username" : "john",
    "timezone" : "Europe/London",
    "lastLoginAt" : "2015-11-24T16:45:53Z",
    "name" : "John Spacey",
    "taskReminder" : false
  } ]
}

Show Current User

Shows the details of the user the provided access token is associated with. In most of the cases this will be user who approved your application.

GET
https://api.capsulecrm.com/api/v2/users/current

Query Parameters

Name Type Description
embed Array of String

Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Can be empty or party.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property user which is a User object.

HTTP/1.1 200
{
  "user" : {
    "id" : 1,
    "locale" : "en_GB",
    "currency" : "EUR",
    "status" : "ACTIVE",
    "emailPreference" : null,
    "clickToCallPreference" : null,
    "preferredEmailFromAddress" : null,
    "party" : {
      "id" : 1,
      "type" : "person",
      "firstName" : "Scott",
      "lastName" : "Spacey",
      "pictureURL" : "https://facehub.appspot.com/default/person?text=SS&size=100"
    },
    "username" : "scott",
    "timezone" : "Europe/London",
    "lastLoginAt" : "2015-12-11T14:01:15Z",
    "name" : "Scott Spacey",
    "taskReminder" : true
  }
}

Show User

Retrieve a specific user by their unique id

GET
https://api.capsulecrm.com/api/v2/users/{userId}

Query Parameters

Name Type Description
embed Array of String

Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Can be empty or party.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property user which is a User object.

HTTP/1.1 200
{
  "user" : {
    "id" : 1,
    "locale" : "en_GB",
    "currency" : "EUR",
    "status" : "ACTIVE",
    "emailPreference" : null,
    "clickToCallPreference" : null,
    "preferredEmailFromAddress" : null,
    "party" : {
      "id" : 1,
      "type" : "person",
      "firstName" : "Scott",
      "lastName" : "Spacey",
      "pictureURL" : "https://facehub.appspot.com/default/person?text=SS&size=100"
    },
    "username" : "scott",
    "timezone" : "Europe/London",
    "lastLoginAt" : "2015-12-11T14:01:15Z",
    "name" : "Scott Spacey",
    "taskReminder" : true
  }
}

Update User

Update an existing user. The body must contain an object with a single property user which must be a user object. Fields that are not included in the requests will remain unchanged.

While it’s not possible to change which party a user is linked to, you can update the party itself by editing it directly.

For an update to succeed your API token must have the user_preference scope.

PUT
https://api.capsulecrm.com/api/v2/users/{userId}

Query Parameters

Name Type Description
embed Array of String

Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Can be empty or party.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single propery user which is a single User object. In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200
{
  "user" : {
    "id" : 1,
    "locale" : "en_GB",
    "currency" : "EUR",
    "status" : "ACTIVE",
    "emailPreference" : "GMAIL",
    "clickToCallPreference" : "SIP",
    "preferredEmailFromAddress" : "scott.spacey@example.com",
    "party" : {
      "id" : 1,
      "type" : "person",
      "firstName" : "Scott",
      "lastName" : "Spacey",
      "pictureURL" : "https://facehub.appspot.com/default/person?text=SS&size=100"
    },
    "username" : "scott",
    "timezone" : "Europe/London",
    "lastLoginAt" : "2015-12-11T14:01:15Z",
    "name" : "Scott Spacey",
    "taskReminder" : true
  }
}