Fields

Resource Fields

Name Type Read-only Description
fielduuid string The fielduuid is unique to this field
title string
type string System Field Types: SUBJECT, MESSAGE, PRIORITY, STATUS, TYPE, TEAM, ASSIGNEE

Custom Field Types: TEXT, TEXTAREA, CHECKBOX, RADIO, SELECT, DATE, FILE, NUMERIC, DECIMAL, YESNO, CASCADINGSELECT, REGEX
key string The key is unique to this field
is_required_for_agents boolean Default: false
is_required_on_resolution boolean Default: false
is_visible_to_customers boolean Default: false
customer_titles Field Locales
is_customer_editable boolean Default: false
is_required_for_customers boolean Default: false
descriptions Field Locales
regular_expression string
sort_order integer
is_enabled boolean
is_system boolean
options Options
created_at timestamp ISO-8601 Format
updated_at timestamp ISO-8601 Format

Metadata




 
 




Actions

Retrieve all fields

GET /api/v1/cases/fields.json

Information

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

Collaborators and Agents can only see the enabled fields.

Response

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

    "fielduuid": "dbc6a83d-5374-42ef-9ccc-c518232ca46d",
    "title": "Serial number",
    "type": "TEXT",
    "key": "serial_number",
    "is_required_for_agents": false,
    "is_required_on_resolution": false,
    "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": 9,
    "is_enabled": true,
    "is_system": false,
    "options": [],
    "created_at": "2015-11-03T18:30:38+05:00",
    "updated_at": "2015-11-03T18:30:38+05:00",

    "resource_type": "case_field"

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

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

Retrieve a field

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

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope conversations

Collaborators and Agents can only see the enabled field.

Response

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

    "fielduuid": "dbc6a83d-5374-42ef-9ccc-c518232ca46d",
    "title": "Serial number",
    "type": "TEXT",
    "key": "serial_number",
    "is_required_for_agents": false,
    "is_required_on_resolution": false,
    "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": 9,
    "is_enabled": true,
    "is_system": false,
    "options": [],
    "created_at": "2015-11-03T18:30:38+05:00",
    "updated_at": "2015-11-03T18:30:38+05:00",

    "resource_type": "case_field"

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

},
        "resource": "case_field"
    }

Add a field

POST /api/v1/cases/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_required_for_agents boolean Required when creating, reply and updating a conversation

Default: false
is_required_on_resolution boolean Required when resolving a conversation

Default: false
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/cases/fields \
     -d '{"title":"Your coffee","type":"SELECT","is_required_for_agents":true,"is_required_on_resolution":true,"is_visible_to_customers":true,"customer_titles":[{"locale":"en-us", "translation": "Your coffee"}, {"locale":"fr", "translation": "Ihren Kaffee"}],descriptions":[],"is_customer_editable":true,"is_required_for_customers":true,"regular_expression":null,"is_enabled":true,"options":[{"values":[{"locale":"en-us","translation":"Yirgacheffe Oromia - Single Origin"}, {"locale":"fr","translation":"Yirgacheffe Oromia - Origine unique"}], "tag":"yirgacheffe-oromia", "sort_order":"1"},{"values":[{"locale":"en-us","translation":"Kenya Kiunyu Ab - Single Origin"}, {"locale":"fr","translation":"Kenya Kiunyu Ab - Origine unique"}], "tag":"kenya-kiunyu-ab", "sort_order":"2"}]}' \
     -H "Content-Type: application/json" \
     -u 'jordan.mitchell@brewfictus.com:jmit6#lsXo'

Response

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

    "fielduuid": "dbc6a83d-5374-42ef-9ccc-c518232ca46d",
    "title": "Serial number",
    "type": "TEXT",
    "key": "serial_number",
    "is_required_for_agents": false,
    "is_required_on_resolution": false,
    "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": 9,
    "is_enabled": true,
    "is_system": false,
    "options": [],
    "created_at": "2015-11-03T18:30:38+05:00",
    "updated_at": "2015-11-03T18:30:38+05:00",

    "resource_type": "case_field"

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

},
        "resource": "case_field"
    }

Update a field

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

Information

Allowed for Admins & Owners
Scope configuration

Parameters

Name Type Mandatory Description
title string
is_required_for_agents boolean
is_required_on_resolution boolean
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/cases/fields/:id \
     -d '{"title":"Your coffee","type":"SELECT","is_required_for_agents":true,"is_required_on_resolution":true,"is_visible_to_customers":true,"customer_titles":[{"id":"20",locale":"en-us", "translation": "Your coffee"}, {"id":"21","locale":"fr", "translation": "Ihren Kaffee"}],descriptions":[],"is_customer_editable":true,"is_required_for_customers":true,"regular_expression":null,"is_enabled":true,"options":[{"id":"4","values":[{"id":"22","locale":"en-us","translation":"Yirgacheffe Oromia - Single Origin"}, {"id":"23","locale":"fr","translation":"Yirgacheffe Oromia - Origine unique"}], "tag":"yirgacheffe-oromia", "sort_order":"1"},{"id":"5","values":[{"id":"24","locale":"en-us","translation":"Kenya Kiunyu Ab - Single Origin"}, {"id":"25","locale":"fr","translation":"Kenya Kiunyu Ab - Origine unique"}], "tag":"kenya-kiunyu-ab", "sort_order":"2"}]}' \
     -H "Content-Type: application/json" \
     -u 'jordan.mitchell@brewfictus.com:jmit6#lsXo'

Response

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

    "fielduuid": "dbc6a83d-5374-42ef-9ccc-c518232ca46d",
    "title": "Serial number",
    "type": "TEXT",
    "key": "serial_number",
    "is_required_for_agents": false,
    "is_required_on_resolution": false,
    "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": 9,
    "is_enabled": true,
    "is_system": false,
    "options": [],
    "created_at": "2015-11-03T18:30:38+05:00",
    "updated_at": "2015-11-03T18:30:38+05:00",

    "resource_type": "case_field"

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

},
        "resource": "case_field"
    }

Reorder fields

PUT /api/v1/cases/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/cases/fields/:id.json

Information

Allowed for Admins & Owners
Scope configuration

Response

{
    "status": 200
}

Delete fields

DELETE /api/v1/cases/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/cases/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/cases/fields/:id/options/:id.json

Information

Allowed for Admins & Owners
Scope configuration

Response

{
    "status": 200
}

Delete options

DELETE /api/v1/cases/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/cases/:id/field/values.json

Information

Allowed for Collaborators
Scope conversations

Response

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

    "resource_type": "case_field"

},
                "value": "3",
                "resource_type": "case_field_value"
            }
        ],
        "resource": "case_field_value",
        "total_count": 1
    }