zendesk_api 0.1.11 → 0.2.1

data/lib/zendesk_api/server/docs/locales.md

@@ -0,0 +1,124 @@
+## Locales
+
+### List Locales
+`GET /api/v2/locales.json`
+
+This lists the translation locales that are available for the account.
+
+#### Allowed For:
+
+ * Anyone
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/locales.json \
+   -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "locales": [
+    {
+      "id":              1,
+      "url":             "https://company.zendesk.com/api/v2/locales/1.json",
+      "locale":          "en-US",
+      "name":            "English",
+      "created_at":      "2009-07-20T22:55:29Z",
+      "updated_at":      "2011-05-05T10:38:52Z"
+    },
+    {
+      "id":              8,
+      "url":             "https://company.zendesk.com/api/v2/locales/8.json",
+      "locale":          "de",
+      "name":            "Deutsch",
+      "created_at":      "2010-12-23T12:45:22Z",
+      "updated_at":      "2012-04-01T10:44:12Z"
+    }
+  ]
+}
+```
+
+### List Locales
+`GET /api/v2/locales/agent.json`
+
+This lists the translation locales that have been localized for agents.
+
+#### Allowed For:
+
+ * Anyone
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/locales/agent.json \
+   -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "locales": [
+    {
+      "id":              1,
+      "url":             "https://company.zendesk.com/api/v2/locales/1.json",
+      "locale":          "en-US",
+      "name":            "English",
+      "created_at":      "2009-07-20T22:55:29Z",
+      "updated_at":      "2011-05-05T10:38:52Z"
+    },
+    {
+      "id":              8,
+      "url":             "https://company.zendesk.com/api/v2/locales/8.json",
+      "locale":          "de",
+      "name":            "Deutsch",
+      "created_at":      "2010-12-23T12:45:22Z",
+      "updated_at":      "2012-04-01T10:44:12Z"
+    }
+  ]
+}
+```
+
+### Show Locale
+`GET /api/v2/locales/{id}.json`
+
+#### Allowed For
+
+ * Anyone
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/locales/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "locale": {
+    "id":              8,
+    "url":             "https://company.zendesk.com/api/v2/locales/8.json",
+    "locale":          "de",
+    "name":            "Deutsch",
+    "created_at":      "2010-12-23T12:45:22Z",
+    "updated_at":      "2012-04-01T10:44:12Z",
+  }
+}
+```
+
+### Show Current Locale
+`GET /api/v2/locales/current.json`
+
+This works exactly like show, but instead of taking an id as argument, it renders the locale
+of the user performing the request.

data/lib/zendesk_api/server/docs/macros.md

@@ -0,0 +1,287 @@
+## Macros
+
+### JSON Format
+Macros are read-only and represented as simple flat JSON objects which have the following keys.
+
+| Name            | Type                       | Comment
+| --------------- | ---------------------------| -------------------
+| id              | integer                    | Automatically assigned when created
+| title           | string                     | The title of the macro
+| active          | boolean                    | Useful for determining if the macro should be displayed
+| restriction     | object                     | Who may access this macro. Will be null when everyone in the account can access it.
+| actions         | [Actions](#actions)        | An object describing what the macro will do
+| created_at      | date                       | The time the macro was created
+| updated_at      | date                       | The time of the last update of the macro
+
+#### Example
+```js
+{
+  "macro": {
+    "id": 25,
+    "title": "Tickets updated <12 Hours",
+    "active": true,
+    "actions": { ... },
+    "restriction": {
+      "type": "User",
+      "id": 4
+    }
+  }
+}
+```
+
+### Actions
+The actions that will be applied to the ticket.
+
+| Name         | Type    | Comment
+| ------------ | ------- | -------
+| field        | string  | The ticket field being modified
+| value        | string  | The new value of the field
+
+#### Example
+```js
+{
+   "actions": [
+       { "field": "status", "value": "solved" },
+       { "field": "assignee", "value": "me" },
+   ]
+}
+```
+
+### List Macros
+`GET /api/v2/macros.json`
+
+Lists all shared and personal macros available to the current user
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/macros.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "macros": [
+     {
+      "id": 25,
+      "title": "Close and Save",
+      "active": true
+      "actions": [ ... ],
+      "restriction": { ... }
+    },
+    {
+      "id": 26,
+      "title": "Assign priority tag",
+      "active": false
+      "actions": [ ... ],
+      "restriction": { ... }
+    }
+  ],
+  "count": 2,
+  "previous_page": null,
+  "next_page": null
+}
+```
+
+### Getting Macros
+`GET /api/v2/macros/{id}.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/macros/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "macro": {
+    "id": 25,
+    "title": "Tickets updated <12 Hours",
+    "active": true
+    "actions": [ ... ],
+    "restriction": { ... }
+  }
+}
+```
+
+### List active Macros
+`GET /api/v2/macros/active.json`
+
+Lists all active shared and personal macros available to the current user
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/macros/active.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "macros": [
+     {
+      "id": 25,
+      "title": "Close and Save",
+      "active": true
+      "actions": [ ... ],
+      "restriction": { ... }
+    },
+    {
+      "id": 28,
+      "title": "Close and redirect to topics",
+      "active": true
+      "actions": [ ... ],
+      "restriction": { ... }
+    }
+  ],
+  "count": 2,
+  "previous_page": null,
+  "next_page": null
+}
+```
+
+### Create Macro
+`POST /api/v2/macros.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/macros.json \
+  -H "Content-Type: application/json" -X POST -d '{"macro": {"title": "Roger Wilco", "actions": [{ "field": "status", "value": "open" }]}}'
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: /api/v2/macros/{new-macro-id}.json
+
+{
+  "macro": {
+    "id":   9873843,
+    "title": "Roger Wilco",
+    ...
+  }
+}
+```
+
+### Update Macro
+`PUT /api/v2/macros/{id}.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/macros/{id}.json \
+  -H "Content-Type: application/json" -X PUT -d '{"macro": {"title": "Roger Wilco II"}}'
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "macro": {
+    "id":   9873843,
+    "title": "Roger Wilco II",
+    ...
+  }
+}
+```
+
+### Delete Macro
+`DELETE /api/v2/macros/{id}.json`
+
+#### Allowed For
+
+ * Agents, restrictions apply on certain actions
+
+#### Using curl
+
+```bash
+curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/macros/{id}.json \
+  -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```
+
+### Apply Macros
+`GET /api/v2/macros/{id}/apply.json`
+
+`GET /api/v2/tickets/{ticket_id}/macros/{id}/apply.json`
+
+Applies a macro to a specific ticket, or to all applicable tickets.
+
+#### Allowed For:
+
+  * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/macros/{id}/apply.json \
+  -u {email_address}:{password}
+```
+
+#### Example Response
+
+```json
+{
+  "result": {
+    "ticket": {
+      "id":               35436,
+      "url":              "https://company.zendesk.com/api/v2/tickets/35436.json",
+      "assignee_id":      235323,
+      "group_id":         98738,
+      "fields": [
+        {
+          "id":    27642,
+          "value": "745"
+        }
+      ],
+      ...
+    },
+    "comment": {
+      "body": "Assigned to Agent Uno.",
+      "public": false
+    }
+  }
+}
+```

data/lib/zendesk_api/server/docs/organizations.md

@@ -0,0 +1,253 @@
+## Organizations
+
+Just as agents can be segmented into Groups in Zendesk, your customers (end-users) can be segmented into Organizations.  You can manually assign customers to an Organization or automatically assign them to an Organization by their email address domain.  Organizations can be used in business rules to route Tickets to Groups of agents or send special email notifications.
+
+### JSON Format
+Organizations are represented as simple flat JSON objects which have the following keys:
+
+| Name            | Type    | Read-only | Mandatory | Comment
+| --------------- | ------- | --------- | --------- | -------
+| id              | integer | yes       | no        | Automatically assigned when creating organization
+| external_id     | string  | no        | no        | A unique external id, you can use this to associate organizations to an external record
+| name            | string  | no        | yes       | The name of the organization
+| created_at      | date    | yes       | no        | The time the organization was created
+| updated_at      | date    | yes       | no        | The time of the last update of the organization
+| domain_names    | array   | no        | no        | An array of domain names associated with this organization
+| details         | string  | no        | no        | In this field you can store any details obout the organization. e.g. the address
+| notes           | string  | no        | no        | In this field you can store any notes you have about the organization
+| group_id        | integer | no        | no        | New tickets from users in this organization will automatically be put in this group
+| shared_tickets  | boolean | no        | no        | End users in this organization are able to see eachother's tickets
+| shared_comments | boolean | no        | no        | End users in this organization are able to see eachother's comments on tickets
+| tags            | array   | no        | no        | The tags of the organization
+
+#### Example
+```js
+{
+  "id":              35436,
+  "external_id":     "ABC123",
+  "url":             "https://company.zendesk.com/api/v2/organizations/35436.json",
+  "name":            "One Organization",
+  "created_at":      "2009-07-20T22:55:29Z",
+  "updated_at":      "2011-05-05T10:38:52Z",
+  "domain_names":    ["example.com", "test.com"],
+  "details":         "This is a kind of organization",
+  "notes":           "",
+  "group_id":        null,
+  "shared_tickets":  true,
+  "shared_comments": true,
+  "tags":            ["enterprise", "other_tag"]
+}
+```
+
+### Listing Organizations
+`GET /api/v2/organizations.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/organizations.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "organizations": [
+    {
+      "id":   35436,
+      "name": "One Organization",
+      ...
+    },
+    {
+      "id":   20057623,
+      "name": "Other Organization",
+      ...
+    },
+  ]
+}
+```
+
+### Autocomplete Organizations
+`POST /api/v2/organizations/autocomplete.json?name={name}`
+
+Returns an array of organizations whose name starts with the value specified
+in the `name` parameter. The name must be at least 2 characters in length.
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/organizations/autocomplete.json \
+  -X POST -d '{"name": "imp"}' -H "Content-Type: application/json" \
+  -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "organizations": [
+    {
+      "id":   35436,
+      "name": "Important Customers",
+      ...
+    },
+    {
+      "id":   20057623,
+      "name": "Imperial College",
+      ...
+    },
+  ]
+}
+```
+
+### Getting Organizations
+`GET /api/v2/organizations/{id}.json`
+
+#### Allowed For
+
+ * Admins
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "organization": {
+    {
+      "id":   35436,
+      "name": "My Organization",
+      ...
+    }
+  }
+}
+```
+
+### Creating Organizations
+`POST /api/v2/organizations.json`
+
+#### Allowed For
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/organizations.json \
+  -H "Content-Type: application/json" -d '{"organization": {"name": "My Organization"}}' \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json
+
+{
+  "organization": {
+    {
+      "id":   35436,
+      "name": "My Organization",
+      ...
+    }
+  }
+}
+```
+
+### Updating Organizations
+`PUT /api/v2/organizations/{id}.json`
+
+#### Allowed For
+
+ * Admins
+
+#### Example Request
+
+```js
+"organization": {
+  "notes": "Something interesting"
+}
+```
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json \
+  -d '{"organization": {"notes": "Something interesting"}}' \
+  -v -u {email_address}:{password} -H "Content-Type: application/json"
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "organization": {
+
+    "id":    35436,
+    "name":  "My Organization",
+    "notes": "Something interesting",
+    ...
+  }
+}
+```
+
+### Deleting Organizations
+`DELETE /api/v2/organizations/{id}.json`
+
+#### Allowed For
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```
+
+### Search Organizations
+`GET /api/v2/organizations/search.json?external_id={external_id}`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/search.json?external_id={search term} \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+See [Listing Organizations](#listing-organizations)