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

Fields

Resource Fields

Name Type Read-only Description
fielduuid string The fielduuid is unique to this field
title string
type string TEXT, TEXTAREA, CHECKBOX, RADIO, SELECT, DATE, FILE, NUMERIC, DECIMAL, YESNO, CASCADINGSELECT, REGEX
key string The key is unique to this field
is_visible_to_customers boolean Default: false
customer_titles locale/fields
is_customer_editable boolean Default: false
is_required_for_customers boolean Default: false
descriptions locale/fields
regular_expression string
sort_order integer
is_enabled boolean
options Options
created_at timestamp ISO-8601 Format
updated_at timestamp ISO-8601 Format



Metadata




 
 



Version 1.0
Last Updated July 04, 2016

Actions

Retrieve all fields

GET /api/v1/users/fields.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users
Ordered by sort_order (ascending)

Collaborators and Agents can only see the enabled fields.

Response

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

    "fielduuid": "aaa7c4de-7633-479b-a26f-38bbe75c6727",
    "title": "Industry",
    "type": "TEXT",
    "key": "industry",
    "is_visible_to_customers": true,
    "customer_titles": 

[






{
    "id": 1,

    "resource_type": "locale_field"

},






{
    "id": 2,

    "resource_type": "locale_field"

}    
],
    "is_customer_editable": true,
    "is_required_for_customers": true,
    "descriptions": [],
    "regular_expression": null,
    "sort_order": 1,
    "is_enabled": true,
    "options": [],
    "created_at": "2015-11-05T10:48:34+05:00",
    "updated_at": "2015-11-05T10:48:34+05:00",

    "resource_type": "user_field"

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

}

        ],
        "resource": "user_field",
        "total_count": 1
    }

Retrieve a field

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

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Collaborators and Agents can only see the enabled field.

Response

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

    "fielduuid": "aaa7c4de-7633-479b-a26f-38bbe75c6727",
    "title": "Industry",
    "type": "TEXT",
    "key": "industry",
    "is_visible_to_customers": true,
    "customer_titles": 

[






{
    "id": 1,

    "resource_type": "locale_field"

},






{
    "id": 2,

    "resource_type": "locale_field"

}    
],
    "is_customer_editable": true,
    "is_required_for_customers": true,
    "descriptions": [],
    "regular_expression": null,
    "sort_order": 1,
    "is_enabled": true,
    "options": [],
    "created_at": "2015-11-05T10:48:34+05:00",
    "updated_at": "2015-11-05T10:48:34+05:00",

    "resource_type": "user_field"

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

}
,
        "resource": "user_field"
    }

Add a field

POST /api/v1/users/fields.json

Information

Allowed for Admins & Owners
Scope configuration

Parameters

Name Type Mandatory Description
type string
TEXT, TEXTAREA, CHECKBOX, RADIO, SELECT, DATE, FILE, NUMERIC, DECIMAL, YESNO, CASCADINGSELECT, REGEX

Note: If field type CHECKBOX, RADIO, SELECT, CASCADINGSELECT Add Options
title string
is_visible_to_customers boolean Default: false
customer_titles string
Only applicable when "Customers can see this field" is enabled
is_customer_editable boolean Only applicable when "Customers can see this field" is enabled

Default: false
is_required_for_customers boolean Only applicable when "Customers can edit this field" is enabled

Default: false
descriptions string User-defined description of this field's purpose
is_enabled boolean Default: true
regular_expression string Regular expression field only. The validation pattern for a field value to be deemed valid.
options string

Request

curl -X POST https://brewfictus.kayako.com/api/v1/users/fields \
     -d '{"title":"Industry","type":"TEXT","is_visible_to_customers":true,"customer_titles":[{"locale":"en-us", "translation": "Industry"}, {"locale":"fr", "translation": "industri"}],descriptions":[],"is_customer_editable":true,"is_required_for_customers":true,"regular_expression":null,"is_enabled":true}' \
     -H "Content-Type: application/json" \
     -u 'jordan.mitchell@brewfictus.com:jmit6#lsXo'

Response

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

    "fielduuid": "aaa7c4de-7633-479b-a26f-38bbe75c6727",
    "title": "Industry",
    "type": "TEXT",
    "key": "industry",
    "is_visible_to_customers": true,
    "customer_titles": 

[






{
    "id": 1,

    "resource_type": "locale_field"

},






{
    "id": 2,

    "resource_type": "locale_field"

}    
],
    "is_customer_editable": true,
    "is_required_for_customers": true,
    "descriptions": [],
    "regular_expression": null,
    "sort_order": 1,
    "is_enabled": true,
    "options": [],
    "created_at": "2015-11-05T10:48:34+05:00",
    "updated_at": "2015-11-05T10:48:34+05:00",

    "resource_type": "user_field"

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

}
,
        "resource": "user_field"
    }

Update a field

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

Information

Allowed for Admins & Owners
Scope configuration

Parameters

Name Type Mandatory Description
title string
is_visible_to_customers boolean
customer_titles string
is_customer_editable boolean
is_required_for_customers boolean
descriptions string
is_enabled boolean
regular_expression string
options string

Request

curl -X PUT https://brewfictus.kayako.com/api/v1/users/fields/:id \
     -d '{"title":"Industry","type":"TEXT","is_visible_to_customers":true,"customer_titles":[{"id":"28",locale":"en-us", "translation": "Industry"}, {"id":"29","locale":"fr", "translation": "industri"}],descriptions":[],"is_customer_editable":true,"is_required_for_customers":true,"regular_expression":null,"is_enabled":true}' \
     -H "Content-Type: application/json" \
     -u 'jordan.mitchell@brewfictus.com:jmit6#lsXo'

Response

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

    "fielduuid": "aaa7c4de-7633-479b-a26f-38bbe75c6727",
    "title": "Industry",
    "type": "TEXT",
    "key": "industry",
    "is_visible_to_customers": true,
    "customer_titles": 

[






{
    "id": 1,

    "resource_type": "locale_field"

},






{
    "id": 2,

    "resource_type": "locale_field"

}    
],
    "is_customer_editable": true,
    "is_required_for_customers": true,
    "descriptions": [],
    "regular_expression": null,
    "sort_order": 1,
    "is_enabled": true,
    "options": [],
    "created_at": "2015-11-05T10:48:34+05:00",
    "updated_at": "2015-11-05T10:48:34+05:00",

    "resource_type": "user_field"

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

}
,
        "resource": "user_field"
    }

Reorder fields

PUT /api/v1/users/fields/reorder.json

Information

Allowed for Admins & Owners
Scope configuration

Parameters

Name Type Mandatory Description
field_ids string
Pass the fields in order you want to set

Response

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

Delete a field

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

Information

Allowed for Admins & Owners
Scope configuration

Response

{
    "status": 200
}

Delete fields

DELETE /api/v1/users/fields.json

Information

Allowed for Admins & Owners
Scope configuration

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Response

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

Options

RESOURCE FIELDS

Name Type Read-only Description
fielduuid string
values Field Locales
sort_order integer Ordering of the option relative to other options
created_at timestamp
ISO-8601 Format
updated_at timestamp
ISO-8601 Format

Reorder options

PUT /api/v1/users/fields/:id/options/reorder.json

Information

Allowed for Admins & Owners
Scope configuration

Parameters

Name Type Mandatory Description
option_ids string
Pass the options in order you want to set

Response

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

Delete a option

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

Information

Allowed for Admins & Owners
Scope configuration

Response

{
    "status": 200
}

Delete options

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

Information

Allowed for Admins & Owners
Scope configuration

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Response

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

Values

RESOURCE FIELDS

Name Type Read-only Description
field Field
value string

Retrieve values

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

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Response

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

    "resource_type": "user_field"

}
,
                "value": "Helpdesk",
                "resource_type": "user_field_value"
            }
        ],
        "resource": "user_field_value",
        "total_count": 1
    }