1. API
  2. v1
  3. CORE
  4. USERS

Users

Resource Fields

Name Type Read-only Description
uuid string
full_name string
legacy_id string
designation string
is_enabled boolean
is_mfa_enabled boolean Whether the user has MFA (Multi-factor authentication) enabled or not.
role Role
avatar string
agent_case_access string SELF, TEAMS, INHERIT-FROM-ROLE, ALL

Only applicable for the role type ADMIN, AGENT, COLLABORATOR

Default: ALL
organization_case_access string REQUESTED, ORGANIZATION

Only applicable for the role type CUSTOMER

Default: REQUESTED
organization Organization
teams Teams
emails Emails
phones Phones
twitter Twitter
facebook Facebook
external_identifiers External Identifiers
custom_fields Custom Fields
pinned_notes_count integer
locale Locale
time_zone string
time_zone_offset string The time zone offset of the person. Useful for calculating the timezone differences.
greeting string
signature string
status_message string
last_seen_user_agent string
last_seen_ip string
last_seen_at timestamp ISO-8601 Format
last_active_at timestamp ISO-8601 Format.

The timestamp when user's direct or indirect property updated like note added or tag created for user.
realtime_channel string Subscribe to this channel for realtime updates
presence_channel string Subscribe to see "who's online"
password_updated_at timestamp ISO-8601 Format
avatar_updated_at timestamp ISO-8601 Format
last_logged_in_at timestamp ISO-8601 Format
last_activity_at timestamp ISO-8601 Format
created_at timestamp ISO-8601 Format
updated_at timestamp ISO-8601 Format



Metadata




 
 



Version 1.0
Last Updated July 04, 2016

Actions

Propositions

RESOURCE FIELDS

Name Type Read-only Description
label string
field string
Field name on which the rules will be applied
type string
NUMERIC, STRING, BOOLEAN, COLLECTION, DATE_ABSOLUTE, DATE_RELATIVE
sub_type string
Depends on type:

NUMERIC: FLOAT, INTEGER

DATE_RELATIVE: PAST, PAST_OR_PRESENT, PRESENT, PAST_OR_FUTURE, FUTURE
group string
DATE for type DATE_ABSOLUTE, DATE_RELATIVE
input_type string
INTEGER, FLOAT, STRING, BOOLEAN, OPTIONS, MULTIPLE, TAGS, DATE_ABSOLUTE, DATE_RELATIVE, AUTOCOMPLETE
operators array
Depends on input_type:

INTEGER, FLOAT: comparison_equalto, comparison_greaterthan, comparison_lessthan

STRING: string_contains_insensitive, comparison_equalto, comparison_not_equalto

BOOLEAN: comparison_equalto, comparison_not_equalto

OPTIONS: comparison_equalto, comparison_not_equalto

TAGS: collection_contains_insensitive, collection_contains_any_insensitive, collection_does_not_contain_insensitive

DATE_ABSOLUTE: date_is, date_is_not

DATE_RELATIVE: date_after_or_on, date_before_or_on

AUTOCOMPLETE: comparison_equalto, comparison_not_equalto
values mixed
Input type: OPTIONS

{"1":"Kayako", "2":"Subscription"}

Input type: INTEGER, FLOAT, BOOLEAN, TAGS, STRING, DATE_ABSOLUTE or TIME

value n/a

Input type: MULTIPLE

{"1":"Kayako", "2":"Subscription"}

Input type: RELATIVE

{"today":"today", "currentweek":"currentweek", "currentmonth":"currentmonth"}

Input type: AUTOCOMPLETE

AUTOCOMPLETE

Retrieve all definitions

GET /api/v1/users/definitions.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Response

  {
      "status": 200,
      "data": [
          {
              "label": "Name",
              "field": "users.fullname",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Organization",
              "field": "users.organizationid",
              "type": "NUMERIC",
              "sub_type": "INTEGER",
              "group": "",
              "input_type": "AUTOCOMPLETE",
              "operators": [
                  "comparison_equalto",
                  "comparison_not_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Role",
              "field": "roles.type",
              "type": "NUMERIC",
              "sub_type": "INTEGER",
              "group": "",
              "input_type": "OPTIONS",
              "operators": [
                  "comparison_equalto",
                  "comparison_not_equalto"
              ],
              "values": {
                  "1": "Owner",
                  "2": "Admin",
                  "3": "Agent",
                  "4": "Collaborator",
                  "5": "Customer"
              },
              "resource_type": "definition"
          },
          {
              "label": "Tags",
              "field": "tags.name",
              "type": "COLLECTION",
              "sub_type": "",
              "group": "",
              "input_type": "TAGS",
              "operators": [
                  "collection_contains_insensitive",
                  "collection_contains_any_insensitive",
                  "collection_does_not_contain_insensitive"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Email",
              "field": "identityemails.address",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Twitter",
              "field": "identitytwitter.screenname",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Facebook",
              "field": "identityfacebook.name",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Phone",
              "field": "identityphones.number",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Last seen",
              "field": "users.lastseenat_relative_past",
              "type": "DATE_RELATIVE",
              "sub_type": "PAST_OR_PRESENT",
              "group": "DATE",
              "input_type": "DATE_RELATIVE",
              "operators": [
                  "date_before_or_on"
              ],
              "values": {
                 "today": "today",
                 "currentweek": "currentweek",
                 "currentmonth": "currentmonth",
                 "currentyear": "currentyear",
                 "tomorrow": "tomorrow",
                 "yesterday": "yesterday",
                 "lastweek": "lastweek",
                 "lastmonth": "lastmonth",
                 "lastyear": "lastyear",
                 "last7days": "last7days",
                 "last30days": "last30days",
                 "last90days": "last90days",
                 "last180days": "last180days",
                 "last365days": "last365days"
              },
              "resource_type": "definition"
          },
          {
              "label": "Last seen",
              "field": "users.lastseenat_absolute",
              "type": "DATE_ABSOLUTE",
              "sub_type": "",
              "group": "DATE",
              "input_type": "DATE_ABSOLUTE",
              "operators": [
                  "date_is",
                  "date_is_not"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Last logged in",
              "field": "loginlogs.loginat_relative_past",
              "type": "DATE_RELATIVE",
              "sub_type": "PAST_OR_PRESENT",
              "group": "DATE",
              "input_type": "DATE_RELATIVE",
              "operators": [
                  "date_before_or_on"
              ],
              "values": {
                 "today": "today",
                 "currentweek": "currentweek",
                 "currentmonth": "currentmonth",
                 "currentyear": "currentyear",
                 "tomorrow": "tomorrow",
                 "yesterday": "yesterday",
                 "lastweek": "lastweek",
                 "lastmonth": "lastmonth",
                 "lastyear": "lastyear",
                 "last7days": "last7days",
                 "last30days": "last30days",
                 "last90days": "last90days",
                 "last180days": "last180days",
                 "last365days": "last365days"
              },
              "resource_type": "definition"
          },
          {
              "label": "Last logged in",
              "field": "loginlogs.loginat_absolute",
              "type": "DATE_ABSOLUTE",
              "sub_type": "",
              "group": "DATE",
              "input_type": "DATE_ABSOLUTE",
              "operators": [
                  "date_is",
                  "date_is_not"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Created at",
              "field": "users.createdat_relative_past",
              "type": "DATE_RELATIVE",
              "sub_type": "PAST_OR_PRESENT",
              "group": "DATE",
              "input_type": "DATE_RELATIVE",
              "operators": [
                  "date_before_or_on"
              ],
              "values": {
                 "today": "today",
                 "currentweek": "currentweek",
                 "currentmonth": "currentmonth",
                 "currentyear": "currentyear",
                 "tomorrow": "tomorrow",
                 "yesterday": "yesterday",
                 "lastweek": "lastweek",
                 "lastmonth": "lastmonth",
                 "lastyear": "lastyear",
                 "last7days": "last7days",
                 "last30days": "last30days",
                 "last90days": "last90days",
                 "last180days": "last180days",
                 "last365days": "last365days"
              },
              "resource_type": "definition"
          },
          {
              "label": "Created at",
              "field": "users.createdat_absolute",
              "type": "DATE_ABSOLUTE",
              "sub_type": "",
              "group": "DATE",
              "input_type": "DATE_ABSOLUTE",
              "operators": [
                  "date_is",
                  "date_is_not"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Updated at",
              "field": "users.updatedat_relative_past",
              "type": "DATE_RELATIVE",
              "sub_type": "PAST_OR_PRESENT",
              "group": "DATE",
              "input_type": "DATE_RELATIVE",
              "operators": [
                  "date_before_or_on"
              ],
              "values": {
                 "today": "today",
                 "currentweek": "currentweek",
                 "currentmonth": "currentmonth",
                 "currentyear": "currentyear",
                 "tomorrow": "tomorrow",
                 "yesterday": "yesterday",
                 "lastweek": "lastweek",
                 "lastmonth": "lastmonth",
                 "lastyear": "lastyear",
                 "last7days": "last7days",
                 "last30days": "last30days",
                 "last90days": "last90days",
                 "last180days": "last180days",
                 "last365days": "last365days"
              },
              "resource_type": "definition"
          },
          {
              "label": "Updated at",
              "field": "users.updatedat_absolute",
              "type": "DATE_ABSOLUTE",
              "sub_type": "",
              "group": "DATE",
              "input_type": "DATE_ABSOLUTE",
              "operators": [
                  "date_is",
                  "date_is_not"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "OS",
              "field": "userbrowsers.os",
              "type": "COLLECTION",
              "sub_type": "",
              "group": "",
              "input_type": "MULTIPLE",
              "operators": [
                  "collection_contains_insensitive",
                  "collection_contains_any_insensitive",
                  "collection_does_not_contain_insensitive"
              ],
              "values": {
                  "OS X": "OS X"
              },
              "resource_type": "definition"
          },
          {
              "label": "Browser",
              "field": "userbrowsers.name",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Browser version",
              "field": "userbrowsers.version",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "City",
              "field": "locations.city",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Country",
              "field": "locations.country",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "OPTIONS",
              "operators": [
                  "comparison_equalto",
                  "comparison_not_equalto"
              ],
              "values": {
                  "AF": "Afghanistan",
                  "AX": "Åland Islands",
                  "AL": "Albania",
                  "GB": "United Kingdom",
                  "US": "United States"
              },
              "resource_type": "definition"
          },
          {
              "label": "Region",
              "field": "locations.region",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Timezone",
              "field": "users.timezone",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "OPTIONS",
              "operators": [
                  "comparison_equalto",
                  "comparison_not_equalto"
              ],
              "values": {
                  "Africa/Abidjan": "Africa/Abidjan",
                  "Africa/Accra": "Africa/Accra",
                  "UTC": "UTC"
              },
              "resource_type": "definition"
          },
          {
              "label": "Language",
              "field": "users.languageid",
              "type": "NUMERIC",
              "sub_type": "INTEGER",
              "group": "",
              "input_type": "OPTIONS",
              "operators": [
                  "comparison_equalto",
                  "comparison_not_equalto"
              ],
              "values": {
                  "1": "de"
              },
              "resource_type": "definition"
          },
          {
              "label": "User enabled",
              "field": "users.isenabled",
              "type": "BOOLEAN",
              "sub_type": "",
              "group": "",
              "input_type": "BOOLEAN",
              "operators": [
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "2FA",
              "field": "users.otptoken",
              "type": "BOOLEAN",
              "sub_type": "",
              "group": "",
              "input_type": "BOOLEAN",
              "operators": [
                  "comparison_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "VIP Customer",
              "field": "userfields.vip_customer",
              "type": "COLLECTION",
              "sub_type": "",
              "group": "",
              "input_type": "MULTIPLE",
              "operators": [
                  "collection_contains_insensitive",
                  "collection_contains_any_insensitive",
                  "collection_does_not_contain_insensitive"
              ],
              "values": {
                  "1": "VIP Customer"
              },
              "resource_type": "definition"
          },
          {
              "label": "Address",
              "field": "userfields.address",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto",
                  "comparison_not_equalto"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Product",
              "field": "userfields.product",
              "type": "NUMERIC",
              "sub_type": "INTEGER",
              "group": "",
              "input_type": "OPTIONS",
              "operators": [
                  "comparison_equalto",
                  "comparison_not_equalto"
              ],
              "values": {
                  "2": "Kayako",
                  "3": "OnDemand",
                  "4": "Subscription",
                  "5": "Download"
              },
              "resource_type": "definition"
          }
      ],
      "resource": "definition",
      "total_count": 24
  }

Autocomplete

Autocomplete

Name Type Read-only Description
users.organizationid Organization

Retrieve smart lists of users

POST /api/v1/users/filter.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Parameters

Name Type Mandatory Description
predicates string
Examples:

{"collection_operator":"OR","collections":[{"proposition_operator":"AND","propositions":[{"field":"users.fullname","operator":"string_contains_insensitive","value":"dave"},{"field":"users.organizationid","operator":"comparison_equalto","value":"1"}]},{"proposition_operator":"OR","propositions":[{"field":"userbrowsers.os","operator":"collection_contains_insensitive","value":"OS X"},{"field":"userbrowsers.os","operator":"collection_contains_insensitive","value":"Windows"}]}]}

Response

    {
        "status": 200,
        "data": [





{
    "id": 2,

    "uuid": "11b60c25-c44c-47b8-9f48-56631cd7fa01",
    "full_name": "Simon Blackhouse",
    "legacy_id": null,
    "designation": "Community Manager",
    "is_enabled": true,
    "is_mfa_enabled": true,
    "role":







{
    "id": 4,

    "resource_type": "role"

},

    "avatar": "https://brewfictus.kayako.com/avatar/get/24ee2d81-ad95-5ae1-a07e-7ccedcdb70b8",
    "agent_case_access": "ALL",
    "organization_case_access": null,
    "organization": {
    "id": 1,

    "resource_type": "organization"

}
,
    "teams": [

    ],
    "emails": [
        {
    "id": 1,

    "resource_type": "identity_email"

}
    ],
    "phones": [




{
    "id": 2,

    "resource_type": "identity_phone"

}

    ],
    "twitter": [],
    "facebook": [],
    "external_identifiers": [],
    "addresses": [
        {
    "id": 1,

    "resource_type": "contact_address"

}

    ],
    "websites": [
        {
    "id": 1,

    "resource_type": "contact_website"

}
    ],
   "custom_fields": [
       {
           "field": {
    "id": 1,

    "resource_type": "user_field"

}
,
           "value": "Customer Success",
           "resource_type": "user_field_value"
       }
    ],
    "pinned_notes_count": 0,
    "locale": "en-us",
    "time_zone": null,
    "time_zone_offset": null,
    "greeting": null,
    "signature": null,
    "status_message": null,
    "last_seen_user_agent": null,
    "last_seen_ip": null,
    "last_seen_at": null,
    "last_active_at": null,
    "realtime_channel": "presence-0c1c9535b26b749f815a22cb459a4a8084be77b6ac9515751ef5a743b190bef3@v1_users_6",
    "presence_channel": "user_presence-281f395f6f51d031a6d3db3489906c98285191ebac41bb744f9323f61af63433@5c98cdaa58dd91ff1119a476e8b3e305d2906d3b",
    "password_updated_at": "2016-03-15T10:38:01+05:00",
    "avatar_updated_at": null,
    "last_logged_in_at": null,
    "last_activity_at": null,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",




    "resource_type": "user"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/users/2"

}

        ],
        "resource": "user",
        "offset": 0,
        "limit": 10,
        "total_count": 1
    }

Retrieve all users

GET /api/v1/users.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users
Ordered by id (descending)

Role permissions

User role type can view
Agent Customers, Collaborators, Agents & Admins
Admin Customers, Collaborators, Agents & Admins

Arguments

Name Type Mandatory Description
role string CUSTOMER, COLLABORATOR, AGENT, ADMIN

OR

Name Type Mandatory Description
ids string For retrieving users by ids, pass comma separated ids

OR

Name Type Mandatory Description
legacy_ids string The comma separated legacy ids

Response

    {
        "status": 200,
        "data": [





{
    "id": 2,

    "uuid": "11b60c25-c44c-47b8-9f48-56631cd7fa01",
    "full_name": "Simon Blackhouse",
    "legacy_id": null,
    "designation": "Community Manager",
    "is_enabled": true,
    "is_mfa_enabled": true,
    "role":







{
    "id": 4,

    "resource_type": "role"

},

    "avatar": "https://brewfictus.kayako.com/avatar/get/24ee2d81-ad95-5ae1-a07e-7ccedcdb70b8",
    "agent_case_access": "ALL",
    "organization_case_access": null,
    "organization": {
    "id": 1,

    "resource_type": "organization"

}
,
    "teams": [

    ],
    "emails": [
        {
    "id": 1,

    "resource_type": "identity_email"

}
    ],
    "phones": [




{
    "id": 2,

    "resource_type": "identity_phone"

}

    ],
    "twitter": [],
    "facebook": [],
    "external_identifiers": [],
    "addresses": [
        {
    "id": 1,

    "resource_type": "contact_address"

}

    ],
    "websites": [
        {
    "id": 1,

    "resource_type": "contact_website"

}
    ],
   "custom_fields": [
       {
           "field": {
    "id": 1,

    "resource_type": "user_field"

}
,
           "value": "Customer Success",
           "resource_type": "user_field_value"
       }
    ],
    "pinned_notes_count": 0,
    "locale": "en-us",
    "time_zone": null,
    "time_zone_offset": null,
    "greeting": null,
    "signature": null,
    "status_message": null,
    "last_seen_user_agent": null,
    "last_seen_ip": null,
    "last_seen_at": null,
    "last_active_at": null,
    "realtime_channel": "presence-0c1c9535b26b749f815a22cb459a4a8084be77b6ac9515751ef5a743b190bef3@v1_users_6",
    "presence_channel": "user_presence-281f395f6f51d031a6d3db3489906c98285191ebac41bb744f9323f61af63433@5c98cdaa58dd91ff1119a476e8b3e305d2906d3b",
    "password_updated_at": "2016-03-15T10:38:01+05:00",
    "avatar_updated_at": null,
    "last_logged_in_at": null,
    "last_activity_at": null,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",




    "resource_type": "user"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/users/2"

}

        ],
        "resource": "user",
        "offset": 0,
        "limit": 10,
        "total_count": 1
    }

Retrieve a user

GET /api/v1/users/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Role permissions

User role type can view
Collaborator Customers
Agent Customers, Collaborators & Agents
Admin Customers, Collaborators, Agents & Admins

Response

    {
        "status": 200,
        "data": 




{
    "id": 2,

    "uuid": "11b60c25-c44c-47b8-9f48-56631cd7fa01",
    "full_name": "Simon Blackhouse",
    "legacy_id": null,
    "designation": "Community Manager",
    "is_enabled": true,
    "is_mfa_enabled": true,
    "role":







{
    "id": 4,

    "resource_type": "role"

},

    "avatar": "https://brewfictus.kayako.com/avatar/get/24ee2d81-ad95-5ae1-a07e-7ccedcdb70b8",
    "agent_case_access": "ALL",
    "organization_case_access": null,
    "organization": {
    "id": 1,

    "resource_type": "organization"

}
,
    "teams": [

    ],
    "emails": [
        {
    "id": 1,

    "resource_type": "identity_email"

}
    ],
    "phones": [




{
    "id": 2,

    "resource_type": "identity_phone"

}

    ],
    "twitter": [],
    "facebook": [],
    "external_identifiers": [],
    "addresses": [
        {
    "id": 1,

    "resource_type": "contact_address"

}

    ],
    "websites": [
        {
    "id": 1,

    "resource_type": "contact_website"

}
    ],
   "custom_fields": [
       {
           "field": {
    "id": 1,

    "resource_type": "user_field"

}
,
           "value": "Customer Success",
           "resource_type": "user_field_value"
       }
    ],
    "pinned_notes_count": 0,
    "locale": "en-us",
    "time_zone": null,
    "time_zone_offset": null,
    "greeting": null,
    "signature": null,
    "status_message": null,
    "last_seen_user_agent": null,
    "last_seen_ip": null,
    "last_seen_at": null,
    "last_active_at": null,
    "realtime_channel": "presence-0c1c9535b26b749f815a22cb459a4a8084be77b6ac9515751ef5a743b190bef3@v1_users_6",
    "presence_channel": "user_presence-281f395f6f51d031a6d3db3489906c98285191ebac41bb744f9323f61af63433@5c98cdaa58dd91ff1119a476e8b3e305d2906d3b",
    "password_updated_at": "2016-03-15T10:38:01+05:00",
    "avatar_updated_at": null,
    "last_logged_in_at": null,
    "last_activity_at": null,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",




    "resource_type": "user"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/users/2"

}
,
        "resource": "user"
    }

Add a user

POST /api/v1/users.json

Information

Allowed for Agents, Admins & Owners
Scope users

Role permissions

User role type can add
Agent Customers
Admin Customers, Collaborators, Agents & Admins

Parameters

Name Type Mandatory Description
role_id integer
The id of the role the user wants to associate with
full_name string
legacy_id string
email string
The Primary email of this user

Mandatory for the role types COLLABORATOR, AGENT, ADMIN
password string
designation string
team_ids string
The comma separated ids.

Mandatory for the role type COLLABORATOR, AGENT, ADMIN
agent_case_access string SELF, TEAMS, INHERIT-FROM-ROLE, ALL

Applicable for the role type COLLABORATOR, AGENT, ADMIN

Default: ALL
organization_case_access string REQUESTED, ORGANIZATION

Only applicable for the role type CUSTOMER

Default: REQUESTED
locale_id integer Locales
signature string Only collaborators, agents & admins can have signature
greeting string Only collaborators, agents & admins can have greeting
status_message string Only collaborators, agents & admins can have status message
time_zone string
field_values array This operation will add field values with requested field keys.

Format:
field_values[field_key] = field_value
field_values[field_key] = field_value

For Options:
CSV options are accepted for multi-select
avatar multipart/form-data

Response

    {
        "status": 201,
        "data": 




{
    "id": 2,

    "uuid": "11b60c25-c44c-47b8-9f48-56631cd7fa01",
    "full_name": "Simon Blackhouse",
    "legacy_id": null,
    "designation": "Community Manager",
    "is_enabled": true,
    "is_mfa_enabled": true,
    "role":







{
    "id": 4,

    "resource_type": "role"

},

    "avatar": "https://brewfictus.kayako.com/avatar/get/24ee2d81-ad95-5ae1-a07e-7ccedcdb70b8",
    "agent_case_access": "ALL",
    "organization_case_access": null,
    "organization": {
    "id": 1,

    "resource_type": "organization"

}
,
    "teams": [

    ],
    "emails": [
        {
    "id": 1,

    "resource_type": "identity_email"

}
    ],
    "phones": [




{
    "id": 2,

    "resource_type": "identity_phone"

}

    ],
    "twitter": [],
    "facebook": [],
    "external_identifiers": [],
    "addresses": [
        {
    "id": 1,

    "resource_type": "contact_address"

}

    ],
    "websites": [
        {
    "id": 1,

    "resource_type": "contact_website"

}
    ],
   "custom_fields": [
       {
           "field": {
    "id": 1,

    "resource_type": "user_field"

}
,
           "value": "Customer Success",
           "resource_type": "user_field_value"
       }
    ],
    "pinned_notes_count": 0,
    "locale": "en-us",
    "time_zone": null,
    "time_zone_offset": null,
    "greeting": null,
    "signature": null,
    "status_message": null,
    "last_seen_user_agent": null,
    "last_seen_ip": null,
    "last_seen_at": null,
    "last_active_at": null,
    "realtime_channel": "presence-0c1c9535b26b749f815a22cb459a4a8084be77b6ac9515751ef5a743b190bef3@v1_users_6",
    "presence_channel": "user_presence-281f395f6f51d031a6d3db3489906c98285191ebac41bb744f9323f61af63433@5c98cdaa58dd91ff1119a476e8b3e305d2906d3b",
    "password_updated_at": "2016-03-15T10:38:01+05:00",
    "avatar_updated_at": null,
    "last_logged_in_at": null,
    "last_activity_at": null,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",




    "resource_type": "user"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/users/2"

}
,
        "resource": "user"
    }

Bulk add users

POST /api/v1/bulk/users.json

Information

Allowed for Agents, Admins & Owners
Scope users

You can insert a maximum of 200 users at a time

Parameters

Name Type Mandatory Description
users array
Array of users to be inserted

Arguments

Name Type Mandatory Description
partial_import boolean By default, even if a single record is invalid, the entire batch is dropped. However, if this parameter is set to true, all the records with no validation errors will be inserted while the invalid records will be returned back.

Request

curl -X POST https://brewfictus.kayako.com/api/v1/bulk/users \
    -d '{"users":[{"full_name" : "John Doe", "role_id" : 4},{"full_name" : "Roger Doe", "legacy_id" : "legacy_101", "role_id" : 4}]}' \
    -H "Content-Type: application/json"

Response

    {
        "status": 202,
        "data": {
    "id": 1,
    "status": "PENDING",
    "created_at": "2015-07-30T06:45:25+05:00",
    "updated_at": "2015-07-30T06:45:25+05:00",
    "resource_type": "bulk_job",
    "resource_url": "https://brewfictus.kayako.com/api/v1/jobs/1"
}
,
        "resource": "job"
    }

Send invitation with details

POST /api/v1/users/invite.json

Information

Allowed for Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
users array
Users to be specified in JSON format. Supporting keys are fullname, email, role_id, team_ids, twitter

Note:
twitter: is optional key
role_id: allowed role types are COLLABORATOR, AGENT, ADMIN and OWNER

Example:
[{"fullname": "Simon Blackhouse", "email": "simon.blackhouse@brewfictus.com", "role_id": 5, "team_ids": [1,2,3], "twitter": "blackhouse"}]

Response

{
    "status": 201
}

Update a user

PUT /api/v1/users/:id.json

Information

Allowed for Agents, Admins & Owners
Scope users

Role permissions

User role type can update
Agent Customers
Admin Customers, Collaborators, Agents & Admins

Parameters

Name Type Mandatory Description
role_id integer The id of the role the user wants to associate with
full_name string
designation string
organization_id integer The id of the organization the user is associated with
team_ids string The comma separated ids. This will replace existing teams with new ones.

Only applicable for the role type ADMIN, AGENT, COLLABORATOR
tags string The comma separated tags. This will replace existing tags with new ones
agent_case_access string SELF, TEAMS, INHERIT-FROM-ROLE, ALL

Only applicable for the role type ADMIN, AGENT, COLLABORATOR
organization_case_access string REQUESTED, ORGANIZATION

Only applicable for the role type CUSTOMER
locale_id integer Locales
signature string Only collaborators, agents & admins can have signature
greeting string Only collaborators, agents & admins can have greeting
status_message string Only collaborators, agents & admins can have status message
time_zone string
is_enabled boolean
field_values array This operation will add or update existing field values with requested field keys.

Format:
field_values[field_key] = field_value
field_values[field_key] = field_value

For Options:
CSV options are accepted for multi-select
WARNING: All options must be passed. The options which are not passed will be removed.
avatar multipart/form-data

Response

    {
        "status": 200,
        "data": 



{
    "id": 1,

    "uuid": "11b60c25-c44c-47b8-9f48-56631cd7fa01",
    "full_name": "Simon Blackhouse",
    "legacy_id": null,
    "designation": "Community Manager",
    "is_enabled": true,
    "is_mfa_enabled": true,
    "role":







{
    "id": 2,

    "resource_type": "role"

},

    "avatar": "https://brewfictus.kayako.com/avatar/get/24ee2d81-ad95-5ae1-a07e-7ccedcdb70b8",
    "agent_case_access": "ALL",
    "organization_case_access": null,
    "organization": {
    "id": 1,

    "resource_type": "organization"

}
,
    "teams": [

    ],
    "emails": [
        {
    "id": 1,

    "resource_type": "identity_email"

}
    ],
    "phones": [




{
    "id": 1,

    "resource_type": "identity_phone"

}

    ],
    "twitter": [],
    "facebook": [],
    "external_identifiers": [],
    "addresses": [
        {
    "id": 1,

    "resource_type": "contact_address"

}

    ],
    "websites": [
        {
    "id": 1,

    "resource_type": "contact_website"

}
    ],
   "custom_fields": [
       {
           "field": {
    "id": 1,

    "resource_type": "user_field"

}
,
           "value": "Customer Success",
           "resource_type": "user_field_value"
       }
    ],
    "pinned_notes_count": 0,
    "locale": "en-us",
    "time_zone": null,
    "time_zone_offset": null,
    "greeting": null,
    "signature": null,
    "status_message": null,
    "last_seen_user_agent": null,
    "last_seen_ip": null,
    "last_seen_at": null,
    "last_active_at": null,
    "realtime_channel": "presence-0c1c9535b26b749f815a22cb459a4a8084be77b6ac9515751ef5a743b190bef3@v1_users_6",
    "presence_channel": "user_presence-281f395f6f51d031a6d3db3489906c98285191ebac41bb744f9323f61af63433@5c98cdaa58dd91ff1119a476e8b3e305d2906d3b",
    "password_updated_at": "2016-03-15T10:38:01+05:00",
    "avatar_updated_at": null,
    "last_logged_in_at": null,
    "last_activity_at": null,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",




    "resource_type": "user"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/users/1"

}
,
        "resource": "user"
    }

Update users

PUT /api/v1/users.json

Information

Allowed for Agents, Admins & Owners
Scope users

Role permissions

User role type can update
Agent Customers
Admin Customers, Collaborators, Agents & Admins

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Parameters

Name Type Mandatory Description
locale_id integer Locales
tags string The comma separated tags. This will replace existing tags with new ones
time_zone string
is_enabled boolean

Response

{
    "status": 200,
    "total_count": 2
}

Update a password

PUT /api/v1/users/:id/password.json

Information

Allowed for Agents, Admins & Owners
Scope users

Role permissions

User role type can update
Agent Customers
Admin Customers, Collaborators, Agents & Admins

Parameters

Name Type Mandatory Description
new_password string

Response

{
    "status": 200
}

Reset password

POST /api/v1/password/reset.json

Information

Allowed for Public

Parameters

Name Type Mandatory Description
email string

Response

{
    "status": 200
}

Delete a user

DELETE /api/v1/users/:id.json

Information

Allowed for Agents, Admins & Owners
Scope users

Role permissions

User role type can delete
Agent Customers
Admin Customers, Collaborators, Agents & Admins

Response

{
    "status": 200
}

Delete users

DELETE /api/v1/users.json

Information

Allowed for Agents, Admins & Owners
Scope users

Role permissions

User role type can delete
Agent Customers
Admin Customers, Collaborators, Agents & Admins

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Response

{
    "status": 200,
    "total_count": 2
}

Posts

RESOURCE FIELDS

Name Type Read-only Description
uuid string
sequence integer
subject string
contents string
creator User
identity Identity
source_channel Channel
attachments Attachments
download_all string
original Resource
created_at timestamp
ISO-8601 Format
updated_at timestamp
ISO-8601 Format

Attachments

RESOURCE FIELDS

Name Type Read-only Description
name string
size integer
width integer
Only if the attachment is image
height integer
Only if the attachment is image
type string
Mime-type of the file
content_id string
Content ID used for inline attachment
alt string
url string
The URL to view the attachment
url_download string
The URL to download the attachment
thumbnails Thumbnails
created_at timestamp
ISO-8601 Format

Thumbnails

RESOURCE FIELDS

Name Type Read-only Description
name string
size integer
width integer
height integer
type string
Mime-type of the file
url string
The URL to view the thumbnail
created_at timestamp
ISO-8601 Format

Retrieve user posts

GET /api/v1/users/:id/posts.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users
Ordered by id (descending)

Arguments

Name Type Mandatory Description
after_id integer
before_id integer

At a time either after_id or before_id is allowed

Response

    {
        "status": 200,
        "data": [
            {
    "id": 1,

    "uuid": "0da0b7df-9528-4e76-af3e-b7419c61f400",
    "client_id": "93a236f0-edac-4b5a-8747-14140da7d4dc",
    "subject": "Customer is using Honey - Blend. So communicate accordingly",
    "contents": "Customer is using Honey - Blend. So communicate accordingly",
    "creator": 



{
    "id": 1,

    "resource_type": "user"

}
,
    "identity": null,
    "source_channel": null,
    "attachments": [],
    "download_all": null,
    "destination_medium": "MESSENGER",
    "source": "MAIL",
    "metadata": {
      "user_agent": "Chrome",
      "page_url": ""
    },
    "original":

                {
     "id": 1,

     "resource_type": "note"

}


    ,
    "post_status": "SENT",
    "post_status_reject_type": null,
    "post_status_reject_reason": null,
    "post_status_updated_at": "2016-11-08T18:44:27+00:00",
    "created_at": "2016-02-17T08:20:18+05:00",
    "updated_at": "2016-02-17T08:20:18+05:00",

    "resource_type": "post"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/users/posts/1"

}

        ],
        "resource": "post",
        "limit": 10,
        "total_count": 1
    }

Retrieve a post

GET /api/v1/users/posts/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Response

    {
        "status": 200,
        "data": {
    "id": 1,

    "uuid": "0da0b7df-9528-4e76-af3e-b7419c61f400",
    "client_id": "93a236f0-edac-4b5a-8747-14140da7d4dc",
    "subject": "Customer is using Honey - Blend. So communicate accordingly",
    "contents": "Customer is using Honey - Blend. So communicate accordingly",
    "creator": 



{
    "id": 1,

    "resource_type": "user"

}
,
    "identity": null,
    "source_channel": null,
    "attachments": [],
    "download_all": null,
    "destination_medium": "MESSENGER",
    "source": "MAIL",
    "metadata": {
      "user_agent": "Chrome",
      "page_url": ""
    },
    "original":

                {
     "id": 1,

     "resource_type": "note"

}


    ,
    "post_status": "SENT",
    "post_status_reject_type": null,
    "post_status_reject_reason": null,
    "post_status_updated_at": "2016-11-08T18:44:27+00:00",
    "created_at": "2016-02-17T08:20:18+05:00",
    "updated_at": "2016-02-17T08:20:18+05:00",

    "resource_type": "post"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/users/posts/1"

}
,
        "resource": "post"
    }