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

Organizations

Resource Fields

Name Type Read-only Description
name string
legacy_id string
is_shared boolean
domains Domains
phone Phone
addresses Addresses
websites Websites
pinned_notes_count integer
custom_fields Fields
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
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"}

Retrieve all definitions

GET /api/v1/organizations/definitions.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Response

  {
      "status": 200,
      "data": [
          {
              "label": "Name",
              "field": "organizations.name",
              "type": "STRING",
              "sub_type": "",
              "group": "",
              "input_type": "STRING",
              "operators": [
                  "string_contains_insensitive",
                  "comparison_equalto"
              ],
              "values": "",
              "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": "",
              "resource_type": "definition"
          },
          {
              "label": "Conversation Access",
              "field": "organizations.conversationaccess",
              "type": "NUMERIC",
              "sub_type": "INTEGER",
              "group": "",
              "input_type": "OPTIONS",
              "operators": [
                  "comparison_equalto"
              ],
              "values": {
                  "0": "Cannot see each other's conversations",
                  "1": "Can see each other's conversations"
              },
              "resource_type": "definition"
          },
          {
              "label": "Created at",
              "field": "organizations.createdat_relative_past",
              "type": "DATE_RELATIVE",
              "sub_type": "PAST_OR_PRESENT",
              "input_type": "DATE_RELATIVE",
              "group": "DATE",
              "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": "organizations.createdat_absolute",
              "type": "DATE_ASOLUTE",
              "sub_type": "",
              "input_type": "DATE_ASOLUTE",
              "group": "DATE",
              "operators": [
                  "date_is",
                  "date_is_not",
                  "date_after_or_on",
                  "date_before_or_on"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Updated at",
              "field": "organizations.updatedat_relative_past",
              "type": "DATE_RELATIVE",
              "sub_type": "PAST_OR_PRESENT",
              "input_type": "DATE_RELATIVE",
              "group": "DATE",
              "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": "organizations.updatedat_absolute",
              "type": "DATE_ASOLUTE",
              "sub_type": "",
              "input_type": "DATE_ASOLUTE",
              "group": "DATE",
              "operators": [
                  "date_is",
                  "date_is_not",
                  "date_after_or_on",
                  "date_before_or_on"
              ],
              "values": null,
              "resource_type": "definition"
          },
          {
              "label": "Build",
              "field": "organizationfields.build",
              "type": "NUMERIC",
              "sub_type": "INTEGER",
              "group": "",
              "input_type": "INTEGER",
              "operators": [
                  "comparison_equalto",
                  "comparison_greaterthan",
                  "comparison_lessthan"
              ],
              "values": "",
              "resource_type": "definition"
          },
          {
              "label": "Product Type",
              "field": "organizationfields.product_type",
              "type": "COLLECTION",
              "sub_type": "",
              "group": "",
              "input_type": "MULTIPLE",
              "operators": [
                  "collection_contains_insensitive",
                  "collection_contains_any_insensitive",
                  "collection_does_not_contain_insensitive"
              ],
              "values": {
                  "7": "fusion",
                  "8": "engage",
                  "9": "case"
              },
              "resource_type": "definition"
          }
      ],
      "resource": "definition",
      "total_count": 7
  }

Retrieve smart lists of organizations

POST /api/v1/organizations/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":"organizations.name","operator":"string_contains_insensitive","value":"Brewfictus"},{"field":"tags.name","operator":"collection_contains_insensitive","value":"brewfictus"}]}]}

Response

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

    "name": "Brewfictus",
    "legacy_id": null,
    "is_shared": false,
    "domains": [
        {
    "id": 1,

    "resource_type": "identity_domain"

}

    ],
    "is_validated": null,
    "phone": [




{
    "id": 1,

    "resource_type": "identity_phone"

}

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

    "resource_type": "contact_address"

}

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

    "resource_type": "contact_website"

}
    ],
    "pinned_notes_count": 0,
    "custom_fields": [
        {
            "field": {
                "id": 1,
                "title": "Industry",
                "key": "industry",
                "resource_type": "organization_field",
                "resource_url": "https://brewfictus.kayako.com/api/v1/organizations/fields/1"
            },
            "value": "Customer Success",
            "resource_type": "organization_field_value"
        }
    ],
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "organization"

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

}

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

Retrieve all organizations

GET /api/v1/organizations.json

Information

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

Arguments

Name Type Mandatory Description
legacy_ids string The comma separated legacy ids

Response

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

    "name": "Brewfictus",
    "legacy_id": null,
    "is_shared": false,
    "domains": [
        {
    "id": 1,

    "resource_type": "identity_domain"

}

    ],
    "is_validated": null,
    "phone": [




{
    "id": 1,

    "resource_type": "identity_phone"

}

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

    "resource_type": "contact_address"

}

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

    "resource_type": "contact_website"

}
    ],
    "pinned_notes_count": 0,
    "custom_fields": [
        {
            "field": {
                "id": 1,
                "title": "Industry",
                "key": "industry",
                "resource_type": "organization_field",
                "resource_url": "https://brewfictus.kayako.com/api/v1/organizations/fields/1"
            },
            "value": "Customer Success",
            "resource_type": "organization_field_value"
        }
    ],
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "organization"

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

}

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

Retrieve an organization

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

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Response

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

    "name": "Brewfictus",
    "legacy_id": null,
    "is_shared": false,
    "domains": [
        {
    "id": 1,

    "resource_type": "identity_domain"

}

    ],
    "is_validated": null,
    "phone": [




{
    "id": 1,

    "resource_type": "identity_phone"

}

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

    "resource_type": "contact_address"

}

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

    "resource_type": "contact_website"

}
    ],
    "pinned_notes_count": 0,
    "custom_fields": [
        {
            "field": {
                "id": 1,
                "title": "Industry",
                "key": "industry",
                "resource_type": "organization_field",
                "resource_url": "https://brewfictus.kayako.com/api/v1/organizations/fields/1"
            },
            "value": "Customer Success",
            "resource_type": "organization_field_value"
        }
    ],
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "organization"

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

}
,
        "resource": "organization"
    }

Retrieve members

GET /api/v1/organizations/:id/members.json

Information

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

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",
        "offset": 0,
        "limit": 10,
        "total_count": 1
    }

Add an organization

POST /api/v1/organizations.json

Information

Allowed for Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
name string
legacy_id string
domains string Comma separated domains
is_shared boolean Default: false
is_validated boolean Default: false
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
tags string Comma separated tags

Response

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

    "name": "Brewfictus",
    "legacy_id": null,
    "is_shared": false,
    "domains": [
        {
    "id": 1,

    "resource_type": "identity_domain"

}

    ],
    "is_validated": null,
    "phone": [




{
    "id": 1,

    "resource_type": "identity_phone"

}

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

    "resource_type": "contact_address"

}

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

    "resource_type": "contact_website"

}
    ],
    "pinned_notes_count": 0,
    "custom_fields": [
        {
            "field": {
                "id": 1,
                "title": "Industry",
                "key": "industry",
                "resource_type": "organization_field",
                "resource_url": "https://brewfictus.kayako.com/api/v1/organizations/fields/1"
            },
            "value": "Customer Success",
            "resource_type": "organization_field_value"
        }
    ],
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "organization"

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

}
,
        "resource": "organization"
    }

Bulk add organizations

POST /api/v1/bulk/organizations.json

Information

Allowed for Agents, Admins & Owners
Scope users

You can insert a maximum of 200 organizations at a time

Parameters

Name Type Mandatory Description
organizations array
Array of organizations 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/organizations \
    -d '{"organizations":[{"name" : "Org_1"},{"name" : "Org_2", "legacy_id" : "legacy_101"}]}' \
    -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"
    }

Update an organization

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

Information

Allowed for Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
name string
domains string Comma separated domains
is_shared boolean
is_validated boolean
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
WARNING: All options must be passed. The options which are not passed will be removed.
tags string Comma separated tags

Response

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

    "name": "Brewfictus",
    "legacy_id": null,
    "is_shared": false,
    "domains": [
        {
    "id": 1,

    "resource_type": "identity_domain"

}

    ],
    "is_validated": null,
    "phone": [




{
    "id": 1,

    "resource_type": "identity_phone"

}

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

    "resource_type": "contact_address"

}

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

    "resource_type": "contact_website"

}
    ],
    "pinned_notes_count": 0,
    "custom_fields": [
        {
            "field": {
                "id": 1,
                "title": "Industry",
                "key": "industry",
                "resource_type": "organization_field",
                "resource_url": "https://brewfictus.kayako.com/api/v1/organizations/fields/1"
            },
            "value": "Customer Success",
            "resource_type": "organization_field_value"
        }
    ],
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "organization"

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

}
,
        "resource": "organization"
    }

Update organizations

PUT /api/v1/organizations.json

Information

Allowed for Agents, Admins & Owners
Scope users

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Parameters

Name Type Mandatory Description
is_shared boolean
tags string Comma separated tags

Response

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

Delete an organization

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

Information

Allowed for Agents, Admins & Owners
Scope users

Response

{
    "status": 200
}

Delete organizations

DELETE /api/v1/organizations.json

Information

Allowed for Agents, Admins & Owners
Scope users

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 organization posts

GET /api/v1/organizations/: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/organizations/posts/1"

}

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

Retrieve a post

GET /api/v1/organizations/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/organizations/posts/1"

}
,
        "resource": "post"
    }

Fields

RESOURCE FIELDS

Name Type Read-only Description
fielduuid string
title string
type string TEXT, TEXTAREA, CHECKBOX, RADIO, SELECT, DATE, FILE, NUMERIC, DECIMAL, YESNO, CASCADINGSELECT, REGEX
key string
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 The validation pattern for a field value to be deemed valid
sort_order integer Ordering of the field relative to other fields
is_enabled boolean Default: true
options Field Options
This can be set for fields of type CHECKBOX, RADIO, SELECT, CASCADINGSELECT
created_at timestamp
ISO-8601 Format
updated_at timestamp
ISO-8601 Format

Retrieve all fields

GET /api/v1/organizations/fields.json

Information

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

Collaborators and Agents can only see the enabled fields.

Response

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

    "fielduuid": "a3b79867-d038-4882-92fa-b44e079aa57b",
    "title": "Customer Success Manager",
    "type": "TEXT",
    "key": "customer_success_manager",
    "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-05T11:22:38+05:00",
    "updated_at": "2015-11-05T11:22:38+05:00",

    "resource_type": "organization_field"

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

}

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

Retrieve a field

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

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Response

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

    "fielduuid": "a3b79867-d038-4882-92fa-b44e079aa57b",
    "title": "Customer Success Manager",
    "type": "TEXT",
    "key": "customer_success_manager",
    "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-05T11:22:38+05:00",
    "updated_at": "2015-11-05T11:22:38+05:00",

    "resource_type": "organization_field"

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

}
,
        "resource": "organization_field"
    }

Add a field

POST /api/v1/organizations/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
title string
is_visible_to_customers boolean Default: false
customer_titles string
is_customer_editable boolean Default: false
is_required_for_customers boolean Default: false
descriptions string User-defined description of this field's purpose
is_enabled boolean Default: true
regular_expression string The validation pattern for a field value to be deemed valid
options string

Request

curl -X POST https://brewfictus.kayako.com/api/v1/organizations/fields \
     -d '{"title":"Customer Success Manager","type":"TEXT","is_visible_to_customers":true,"customer_titles":[{"locale":"en-us", "translation": "Customer Success Manager"}, {"locale":"fr", "translation": "Succès Client Gestionnaire"}],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": "a3b79867-d038-4882-92fa-b44e079aa57b",
    "title": "Customer Success Manager",
    "type": "TEXT",
    "key": "customer_success_manager",
    "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-05T11:22:38+05:00",
    "updated_at": "2015-11-05T11:22:38+05:00",

    "resource_type": "organization_field"

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

}
,
        "resource": "organization_field"
    }

Update a field

PUT /api/v1/organizations/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 User-defined description of this field's purpose
is_enabled boolean
regular_expression string The validation pattern for a field value to be deemed valid
options string

Request

curl -X PUT https://brewfictus.kayako.com/api/v1/organizations/fields/:id \
     -d '{"title":"Customer Success Manager","type":"TEXT","is_visible_to_customers":true,"customer_titles":[{"id":"30",locale":"en-us", "translation": "Customer Success Manager"}, {"locale":"fr", "translation": "Succès Client Gestionnaire"}],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": "a3b79867-d038-4882-92fa-b44e079aa57b",
    "title": "Customer Success Manager",
    "type": "TEXT",
    "key": "customer_success_manager",
    "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-05T11:22:38+05:00",
    "updated_at": "2015-11-05T11:22:38+05:00",

    "resource_type": "organization_field"

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

}
,
        "resource": "organization_field"
    }

Reorder fields

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

Information

Allowed for Admins & Owners
Scope configuration

Parameters

Name Type Mandatory Description
field_ids string
The comma separated ids

Response

{
    "status": 200
}

Delete a field

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

Information

Allowed for Admins & Owners
Scope configuration

Response

{
    "status": 200
}

Delete fields

DELETE /api/v1/organization/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
}

Fields options

RESOURCE FIELDS

Name Type Read-only Description
fielduuid string
values Field Locales
sort_order integer
created_at timestamp
ISO-8601 Format
updated_at timestamp
ISO-8601 Format

Reorder field options

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

Information

Allowed for Admins & Owners
Scope configuration

Parameters

Name Type Mandatory Description
option_ids string
comma separated option ids

Response

{
    "status": 200
}

Delete a field option

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

Information

Allowed for Admins & Owners
Scope configuration

Response

{
    "status": 200
}

Delete field options

DELETE /api/v1/organizations/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
}

Fields values

RESOURCE FIELDS

Name Type Read-only Description
field Fields
value mixed

Retrieve field values

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

Information

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

Response

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

    "resource_type": "organization_field"

}
,
                "value": "brewfictus",
                "resource_type": "organization_field_value"
            }
        ],
        "resource": "organization_field_value",
        "total_count": 1
    }

Update field values

PUT /api/v1/organizations/:id/field/values.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
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
WARNING: All options must be passed. The options which are not passed will be removed.

Response

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

    "resource_type": "organization_field"

}
,
                "value": "brewfictus",
                "resource_type": "organization_field_value"
            }
        ],
        "resource": "organization_field_value",
        "total_count": 1
    }

Activities

RESOURCE FIELDS

Name Type Read-only Description
activity string
An identifier for the activity. create_organization, update_organization etc. Should contain a-Z and underscore.
actor Actor
Who did it. The user/system that carried out this activity
verb string
What they did. CREATE, SHARE, JOIN, LIKE, NOTIFY etc.
summary string
actions Actions
object Object
Activity performed on. Case, Team, Event etc.
object_actor Actor
If this activity's object is itself another activity, this property specifies the original activity's actor
location Location
place Place
Where the activity was carried out
target Target
Describes object targeted by activity
result Result
Describes the result of the activity
in_reply_to In Reply To
Identifying an object which can be considered as a response to the base object
participant string
Describes participant of the activity
portal string
weight float
Weight decides the priority/importance of this activity
ip_address string
created_at timestamp
ISO-8601 Format

Actions

RESOURCE FIELDS

Name Type Read-only Description
action string
CREATED, UPDATED, DELETED
field string
old_value string
new_value string
old_object Resource
new_object Resource

Actor

RESOURCE FIELDS

Name Type Read-only Description
name string
titile string
prefix string
url string
full_title string
image string
preposition string
original Resource

Object

RESOURCE FIELDS

Name Type Read-only Description
name string
titile string
prefix string
url string
full_title string
image string
preposition string
original Resource

Place

RESOURCE FIELDS

Name Type Read-only Description
name string
titile string
prefix string
url string
full_title string
image string
preposition string
original Resource

Target

RESOURCE FIELDS

Name Type Read-only Description
name string
titile string
prefix string
url string
full_title string
image string
preposition string
original Resource

Result

RESOURCE FIELDS

Name Type Read-only Description
name string
titile string
prefix string
url string
full_title string
image string
preposition string
original Resource

InReplyTo

RESOURCE FIELDS

Name Type Read-only Description
name string
titile string
prefix string
url string
full_title string
image string
preposition string
original Resource

Participant

RESOURCE FIELDS

Name Type Read-only Description
name string
titile string
prefix string
url string
full_title string
image string
preposition string
original Resource

Location

RESOURCE FIELDS

Name Type Read-only Description
city string
region string
region_code string
area_code string
time_zone string
organization string
net_speed string
The network speed associated with the IP address.
country string
country_code string
postal_code string
latitude string
longitude string
metro_code string
The metro code associated with the IP address.
These are only available for IP addresses in the US.
isp string
The name of the Internet Service Provider associated with the IP address.

Retrieve all activities

GET /api/v1/organizations/:id/activities.json

Information

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

Arguments

Name Type Mandatory Description
minimum_weight float Filter activities by their minimum weight
since timestamp Filter activities newer than specified date
until timestamp Filter activities older than specified date
sort_order string ASC, DESC

Default: DESC

Response

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

    "activity": "create_case",
    "actor": {
    "name": "user",
    "title": "Simon Blackhouse",
    "prefix": "@",
    "url": "https://brewfictus.kayako.com/user/1",
    "full_title": "Simon Blackhouse",
    "image": "",
    "preposition": null,
    "original": 



{
    "id": 1,

    "resource_type": "user"

}
,
    "resource_type": "activity_actor"
}
,
    "verb": "create",
    "summary": "<@https://brewfictus.kayako.com/user/1|Phoebe Todd> created <https://brewfictus.kayako.com/case/view/1|Atmosphere Coffee, Inc annual maintenance>",
    "actions": [],
    "object": {
    "id": 1,

    "resource_type": "case"

}
,
    "object_actor": null,
    "location": null,
    "place": null,
    "target": null,
    "result": null,
    "in_reply_to": null,
    "participant": null,
    "portal": "API",
    "weight": 0.8,
    "ip_address": null,
    "created_at": "2015-07-27T11:35:09+05:00",

    "resource_type": "activity"
}

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

Identities

Domains

RESOURCE FIELDS

Name Type Read-only Description
domain string
is_primary boolean This returns true for the primary domain of the user

Default: false
is_validated boolean Specifies if the domain is validated

Default: false
created_at timestamp
ISO-8601 Format
updated_at timestamp
ISO-8601 Format

Retrieve all domains

GET /api/v1/identities/domains.json

Information

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

Arguments

Name Type Mandatory Description
organization_id integer
The id of the Organization

Response

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

    "domain": "brewfictus.com",
    "is_primary": true,
    "is_validated": false,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "identity_domain"

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

}

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

Retrieve a domain

GET /api/v1/identities/domains/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Response

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

    "domain": "brewfictus.com",
    "is_primary": true,
    "is_validated": false,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "identity_domain"

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

}
,
        "resource": "identity_domain"
    }

Add a domain

POST /api/v1/identities/domains.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
organization_id integer
The id of the Organization
domain string
is_primary boolean Default: False
is_validated boolean Applicable for the role type AGENT, ADMIN, OWNER

Default: false

Response

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

    "domain": "brewfictus.com",
    "is_primary": true,
    "is_validated": false,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "identity_domain"

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

}
,
        "resource": "identity_domain"
    }

Update a domain

PUT /api/v1/identities/domains/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
is_primary boolean
is_validated boolean

Response

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

    "domain": "brewfictus.com",
    "is_primary": true,
    "is_validated": false,
    "created_at": "2016-03-15T10:38:01+05:00",
    "updated_at": "2016-03-15T10:38:01+05:00",

    "resource_type": "identity_domain"

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

}
,
        "resource": "identity_domain"
    }

Delete domain

DELETE /api/v1/identities/domains/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Response

{
    "status": 200
}

Delete domains

DELETE /api/v1/identities/domains.json

Information

Allowed for Admins & Owners
Scope users

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Response

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

Notes

RESOURCE FIELDS

Name Type Read-only Description
body_text string
body_html string
is_pinned boolean Default: false
pinned_by User
user User
attachments Attachments
download_all string
Download all attachment as zip
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 all notes

GET /api/v1/organizations/:id/notes.json

Information

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

Arguments

Name Type Mandatory Description
is_pinned boolean

Response

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

     "body_text": "Customer is using Honey - Blend. So communicate accordingly",
     "body_html": null,
     "is_pinned": true,
     "pinned_by": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "user": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "attachments": [],
     "download_all": null,
     "created_at": "2016-02-17T08:20:18+05:00",
     "updated_at": "2016-02-17T08:20:18+05:00",

     "resource_type": "note"

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

}

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

Retrieve a note

GET /api/v1/organizations/:id/notes/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Response

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

     "body_text": "Customer is using Honey - Blend. So communicate accordingly",
     "body_html": null,
     "is_pinned": true,
     "pinned_by": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "user": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "attachments": [],
     "download_all": null,
     "created_at": "2016-02-17T08:20:18+05:00",
     "updated_at": "2016-02-17T08:20:18+05:00",

     "resource_type": "note"

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

}
,
        "resource": "note"
    }

Add a note

POST /api/v1/organizations/:id/notes.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
contents string
is_html boolean If set to true then system will parse the contents through the purify service and render them

Default: false
files[] array File Upload multipart/form-data
attachment_file_ids CSV

Response

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

     "body_text": "Customer is using Honey - Blend. So communicate accordingly",
     "body_html": null,
     "is_pinned": true,
     "pinned_by": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "user": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "attachments": [],
     "download_all": null,
     "created_at": "2016-02-17T08:20:18+05:00",
     "updated_at": "2016-02-17T08:20:18+05:00",

     "resource_type": "note"

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

}
,
        "resource": "note"
    }

Update a note

PUT /api/v1/organizations/:id/notes/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
is_pinned boolean
If set to true then it wil appear as a pinned in the organization, user and conversation timelines.

Response

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

     "body_text": "Customer is using Honey - Blend. So communicate accordingly",
     "body_html": null,
     "is_pinned": true,
     "pinned_by": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "user": 



{
    "id": 1,

    "resource_type": "user"

}
,
     "attachments": [],
     "download_all": null,
     "created_at": "2016-02-17T08:20:18+05:00",
     "updated_at": "2016-02-17T08:20:18+05:00",

     "resource_type": "note"

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

}
,
        "resource": "note"
    }

Tags

RESOURCE FIELDS

Name Type Read-only Description
name string

Retrieve all tags

GET /api/v1/organizations/:id/tags.json

Information

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

Response

    {
        "status": 200,
        "data": [
            {
    "id": 1,
    "name": "important",
    "resource_type": "tag"
}
        ],
        "resource": "tag",
        "total_count": 1
    }

Add tags

POST /api/v1/organizations/:id/tags.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
tags string
Comma separated tags

Response

    {
        "status": 201,
        "data": [
            {
    "id": 1,
    "name": "important",
    "resource_type": "tag"
}
        ],
        "resource": "tag",
        "total_count": 1
    }

Replace tags

PUT /api/v1/organizations/:id/tags.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Parameters

Name Type Mandatory Description
tags string
Comma separated tags

Response

    {
        "status": 200,
        "data": [
            {
    "id": 1,
    "name": "important",
    "resource_type": "tag"
}
        ],
        "resource": "tag",
        "total_count": 1
    }

Remove tags

DELETE /api/v1/organizations/:id/tags.json

Information

Allowed for Collaborators, Agents, Admins & Owners
Scope users

Arguments

Name Type Mandatory Description
tags string
Comma separated tags

Response

    {
        "status": 200,
        "data": [
            {
    "id": 1,
    "name": "important",
    "resource_type": "tag"
}
        ],
        "resource": "tag",
        "total_count": 1
    }