zendesk_api 0.1.11 → 0.2.1

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

@@ -0,0 +1,117 @@
+## Problems
+
+### JSON Format
+Tickets are represented as JSON objects which have the following keys:
+
+| Name                  | Type                                     | Read-only | Mandatory | Comment
+| --------------------- | ---------------------------------------- | --------- | --------- | -------
+| id                    | integer                                  | yes       | no        | Automatically assigned when creating tickets
+| url                   | string                                   | yes       | no        | The API url of this ticket
+| external_id           | string                                   | no        | no        | A unique external id, you can use this to link Zendesk tickets to local records
+| type                  | string                                   | no        | no        | The type of this ticket, i.e. "problem", "incident", "question" or "task"
+| subject               | string                                   | no        | no        | The value of the subject field for this ticket
+| description           | string                                   | yes       | no        | The first comment on the ticket
+| priority              | string                                   | no        | no        | Priority, defines the urgency with which the ticket should be addressed: "urgent", "high", "normal", "low"
+| status                | string                                   | no        | no        | The state of the ticket, "new", "open", "pending", "hold", "solved", "closed"
+| recipient             | string                                   | yes       | no        | The original recipient e-mail address of the ticket
+| requester_id          | integer                                  | no        | yes       | The user who requested this ticket
+| submitter_id          | integer                                  | yes       | no        | The user who submitted the ticket; this is the currently authenticated API user
+| assignee_id           | integer                                  | no        | no        | What agent is currently assigned to the ticket
+| organization_id       | integer                                  | yes       | no        | The organization of the requester
+| group_id              | integer                                  | no        | no        | The group this ticket is assigned to
+| collaborator_ids      | array                                    | no        | no        | Who are currently CC'ed on the ticket
+| forum_topic_id        | integer                                  | no        | no        | The topic this ticket originated from, if any
+| problem_id            | integer                                  | no        | no        | The problem this incident is linked to, if any
+| has_incidents         | boolean                                  | yes       | no        | Is true of this ticket has been marked as a problem, false otherwise
+| due_at                | date                                     | no        | no        | If this is a ticket of type "task" it has a due date.  Due date format uses [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format.
+| tags                  | array                                    | no        | no        | The array of tags applied to this ticket
+| via                   | [Via](ticket_audits.html#the-via-object) | yes       | no        | This object explains how the ticket was created
+| custom_fields         | array                                    | no        | no        | The custom fields of the ticket
+| satisfaction_rating   | object                                   | yes       | no        | The satisfaction rating of the ticket, if it exists
+| sharing_agreement_ids | array                                    | yes       | no        | The ids of the sharing agreements used for this ticket
+| created_at            | date                                     | yes       | no        | When this record was created
+| updated_at            | date                                     | yes       | no        | When this record last got updated
+
+#### Example
+```js
+{
+  "id":               35436,
+  "url":              "https://company.zendesk.com/api/v2/tickets/35436.json",
+  "external_id":      "ahg35h3jh",
+  "created_at":       "2009-07-20T22:55:29Z",
+  "updated_at":       "2011-05-05T10:38:52Z",
+  "type":             "incident",
+  "subject":          "Help, my printer is on fire!",
+  "description":      "The fire is very colorful.",
+  "priority":         "high",
+  "status":           "open",
+  "recipient":        "support@company.com",
+  "requester_id":     20978392,
+  "submitter_id":     76872,
+  "assignee_id":      235323,
+  "organization_id":  509974,
+  "group_id":         98738,
+  "collaborator_ids": [35334, 234],
+  "forum_topic_id":   72648221,
+  "problem_id":       9873764,
+  "has_incidents":    false,
+  "due_at":           null,
+  "tags":             ["enterprise", "other_tag"],
+  "via": {
+    "channel": "web"
+  },
+  "custom_fields": [
+    {
+      "id":    27642,
+      "value": "745"
+    },
+    {
+      "id":    27648,
+      "value": "yes"
+    }
+  ],
+  "satisfaction_rating": {
+    "score": "good",
+    "comment": "Great support!"
+  },
+  "sharing_agreement_ids": [84432]
+}
+```
+
+### Listing Ticket Problems
+`GET /api/v2/problems.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/problems.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "tickets": [
+    {
+      "id":          33,
+      "subject":     "My printer is on fire",
+      "description": "The fire is very colorful.",
+      "status":      "open",
+      ...
+    },
+    {
+      "id":          34,
+      "subject":     "The printer is on fire over here too",
+      "description": "The fire is very colorful as well!",
+      "status":      "pending",
+      ...
+    },
+  ]
+}
+```

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

@@ -0,0 +1,256 @@
+## Requests
+
+A request is an end-users perspective on a ticket, this API end point is thus for end-users to view, update and create tickets they have access to. End-users can only see public comments and certain fields of a ticket, and you should use the API token to impersonate an end-user when using this end point.
+
+### JSON Format
+Requests are represented as JSON objects which have the following keys:
+
+| Name             | Type                                     | Read-only | Mandatory | Comment
+| ---------------- | ---------------------------------------- | --------- | --------- | -------
+| id               | integer                                  | yes       | no        | Automatically assigned when creating requests
+| url              | string                                   | yes       | no        | The API url of this request
+| subject          | string                                   | no        | no        | The value of the subject field for this request
+| description      | string                                   | yes       | no        | The first comment on the request
+| status           | string                                   | no        | no        | The state of the request, "new", "open", "pending", "hold", "solved", "closed"
+| custom_fields    | Array                                    | no        | no        | The fields and entries for this request
+| organization_id  | integer                                  | yes       | no        | The organization of the requester
+| via              | [Via](ticket_audits.html#the-via-object) | yes       | no        | This object explains how the request was created
+| created_at       | date                                     | yes       | no        | When this record was created
+| updated_at       | date                                     | yes       | no        | When this record last got updated
+
+#### Example
+```js
+{
+  "id":               35436,
+  "url":              "https://company.zendesk.com/api/v2/requests/35436.json",
+  "created_at":       "2009-07-20T22:55:29Z",
+  "updated_at":       "2011-05-05T10:38:52Z",
+  "subject":          "Help, my printer is on fire!",
+  "description":      "The fire is very colorful.",
+  "status":           "open",
+  "organization_id":  509974,
+  "via": {
+    "channel": "web"
+  }
+}
+```
+
+#### Request Comments
+Comments represent the public conversation between Requesters, Collaborators and Agents on a request.
+
+Ticket comments have the following keys:
+
+| Name            | Type    | Read-only | Comment
+| --------------- | ------- | --------- | -------
+| id              | integer | yes       | Automatically assigned when creating events
+| body            | string  | yes       | The actual comment made by the author
+| attachments     | array   | yes       | The attachments on this comment as [Attachment](attachments.md) objects
+| created_at      | date    | yes       | When this comment was created
+
+#### Example
+```js
+{
+  "id":     1274,
+  "body":   "Thanks for your help!",
+  "attachments": [
+    {
+      "id":           498483,
+      "name":         "crash.log",
+      "content_url":  "https://company.zendesk.com/attachments/crash.log",
+      "content_type": "text/plain",
+      "size":         2532,
+      "thumbnails":   []
+    }
+  ],
+ "created_at": "2009-07-20T22:55:29Z"
+}
+```
+
+### Listing Requests
+`GET /api/v2/requests.json`
+
+`GET /api/v2/requests/open.json`
+
+`GET /api/v2/requests/solved.json`
+
+`GET /api/v2/requests/ccd.json`
+
+`GET /api/v2/users/{id}/requests.json`
+
+#### Allowed For
+
+ * End Users
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/requests.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "requests": [
+    {
+      "id": 33,
+      "status": "open",
+      "description": "My printer is on fire!",
+      ...
+    }
+    {
+      "id": 34,
+      "status": "closed",
+      "description": "I can't find my keys",
+      ...
+    },
+  ]
+}
+```
+
+### Getting Requests
+`GET /api/v2/requests/{id}.json`
+
+#### Allowed For
+
+ * End Users
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/requests/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "request": {
+    "id": 33,
+    "status": "open",
+    "description": "My printer is on fire!",
+    ...
+  }
+}
+```
+
+### Creating Requests
+`POST /api/v2/requests.json`
+
+#### Allowed For
+
+ * End Users
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/requests.json \
+  -d '{"request": {"subject": "Help!", "comment": {"body": "My printer is on fire!", "uploads": [...]}}}' \
+  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/requests/{id}.json
+
+{
+  "request": {
+    "id": 33,
+    "status": "new",
+    "description": "My printer is on fire!",
+    ...
+  }
+}
+```
+
+### Updating Requests
+`PUT /api/v2/requests/{id}.json`
+
+#### Allowed For
+
+ * End Users
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/requests/{id}.json \
+  -d '{"request": {"comment": {"body": "Thanks!"}}}' \
+  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "request": {
+    "id": 33,
+    "status": "new",
+    "description": "My printer is on fire!",
+    ...
+  }
+}
+```
+
+### Listing Comments
+`GET /api/v2/requests/{id}/comments.json`
+
+#### Allowed For
+
+* End Users
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/requests/{id}/comments.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "comments": [
+    {
+      "id": 43,
+      "body": "Thanks for your help!",
+      ...
+    },
+    ...
+  ]
+}
+```
+
+### Getting Comments
+`GET /api/v2/requests/{request_id}/comments/{id}.json`
+
+#### Allowed For
+
+* End Users
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/requests/{request_id}/comments/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "comment": {
+    "id": 43,
+    "body": "Thanks!",
+    ...
+  }
+}
+```

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

@@ -0,0 +1,136 @@
+## Satisfaction Ratings
+
+If you have enabled satisfaction ratings for your account, this end point allows you to quickly retrieve all ratings.
+
+### JSON Format
+
+| Name            | Type    | Read-only | Mandatory | Comment
+| --------------- | ------- | --------- | --------- | -------
+| id              | integer | yes       | no        | Automatically assigned upon creation
+| url             | string  | yes       | no        | The API url of this rating
+| assignee_id     | integer | yes       | yes       | The id of agent assigned to at the time of rating
+| group_id        | integer | yes       | yes       | The id of group assigned to at the time of rating
+| requester_id    | integer | yes       | yes       | The id of ticket requester submitting the rating
+| ticket_id       | integer | yes       | yes       | The id of ticket being rated
+| score           | string  | yes       | yes       | The rating: "offered", "unoffered", "good" or "bad"
+| created_at      | date    | yes       | no        | The time the satisfaction rating got created
+| updated_at      | date    | yes       | no        | The time the satisfaction rating got updated
+| comment         | string  | yes       | no        | The comment received with this rating, if available
+
+#### Example
+```js
+{
+  "id":              35436,
+  "url":             "https://company.zendesk.com/api/v2/satisfaction_ratings/62.json",
+  "assignee_id":     135,
+  "group_id":        44,
+  "requester_id":    7881,
+  "ticket_id":       208,
+  "score":           "good",
+  "updated_at":      "2011-07-20T22:55:29Z",
+  "created_at":      "2011-07-20T22:55:29Z"
+}
+```
+
+### List Satisfaction Ratings
+`GET /api/v2/satisfaction_ratings.json`
+
+Lists all received satisfaction rating requests ever issued for your account. To only list
+the satisfaction ratings submitted by your customers, use the "received" end point below instead.
+
+#### Allowed For:
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/satisfaction_ratings.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "satisfaction_ratings": [
+    {
+      "id":              35436,
+      "url":             "https://company.zendesk.com/api/v2/satisfaction_ratings/35436.json",
+      "assignee_id":     135,
+      "group_id":        44,
+      "requester_id":    7881,
+      "ticket_id":       208,
+      "score":           "good",
+      "updated_at":      "2011-07-20T22:55:29Z",
+      "created_at":      "2011-07-20T22:55:29Z",
+      "comment":         "Awesome support!"
+    },
+    {
+      "id":              120447,
+      ...
+      "created_at":      "2012-02-01T04:31:29Z",
+      "updated_at":      "2012-02-02T10:32:59Z"
+    }
+  ]
+}
+```
+
+
+### List Received Satisfaction Ratings
+`GET /api/v2/satisfaction_ratings/received.json`
+
+Lists ratings provided by customers.
+
+#### Allowed For:
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/satisfaction_ratings/received.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+As above.
+
+
+### Show Satisfaction Rating
+`GET /api/v2/satisfaction_ratings/{id}.json`
+
+#### Allowed For:
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/satisfaction_ratings/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "satisfaction_rating": {
+    "id":              35436,
+    "url":             "https://company.zendesk.com/api/v2/satisfaction_ratings/35436.json",
+    "assignee_id":     135,
+    "group_id":        44,
+    "requester_id":    7881,
+    "ticket_id":       208,
+    "score":           "good",
+    "updated_at":      "2011-07-20T22:55:29Z",
+    "created_at":      "2011-07-20T22:55:29Z",
+    "comment":         { ... }
+  }
+}
+```