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 request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `party` (the user party). Read more about `embed`.

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",
    "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",
    "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 cases this will be the user who approved your application.

Each user has an associated Party record. It stores additional information about the user, including email addresses, phone numbers etc. In order to retrieve user information stored in a user's party record, you can embed party in the query.

GET

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

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `party` (the user party). Read more about `embed`.

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",
    "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.

GET

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

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `party` (the user party). Read more about `embed`.

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",
    "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 request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are `party` (the user party). Read more about `embed`.

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
  }
}