Snappy API Documentation

Introduction

All Snappy API end-points begin with https://app.besnappy.com/api/v1/ and use the HTTPS protocol. All requests should also pass a username and password or API key to authenticate via Basic Auth.

You may retrieve your API key via the "Your Settings" menu in Snappy. Once in the settings menu, the security tab will provide access to your API key. When authenticating via API key, pass the key as the "username" and any string (such as "x) as the password.

Response payloads are typically JSON; however, a few end-points return only a simple string identifier.

Rate Limiting

The current Snappy API rate limit is 200 requests per minute.

Endpoints

• Accounts
• Search
• Mailboxes
• Staff
• Contacts
• Waiting Tickets
• Inbox Tickets
• Your Tickets
• Ticket Details
• Ticket Notes
• Creating Tickets & Adding Notes
• Updating Ticket Tags
• Updating Ticket Status
• Deleting A Ticket
• Documents
• Downloading Documents
• Downloading Attachments
• Reading Team Wall
• Posting To Team Wall
• Deleting Wall Posts
• Commenting On Wall Posts
• Deleting Wall Comments
• Liking Wall Posts
• Unliking Wall Posts
• Searching FAQs
• Creating & Editing FAQs
• Creating & Editing FAQ Topics
• Creating & Editing FAQ Questions

GET /accounts

Retrieve all of the accounts the authenticated account has access to.

[
    {
        "id": 3,
        "organization": "Snappy Help",
        "domain": "help.besnappy.com",
        "plan_id": 1,
        "active": 1,
        "created_at": "2012-12-05 15:24:20",
        "updated_at": "2013-05-07 19:48:06",
        "custom_domain": ""
    }
]

GET /account/{id}/search

Perform a fuzzy search on an account's tickets.

Two items should be passed in the query string: query and page. The query parameter is your plain text search query. The page parameter allows you to indicate which page of results should be returned. Search results are returned with items for page.

In the search response, the meta property will give you the total amount of search results, not just the total for the current page.

{
    "meta": {
        "total": 15,
        "page": 1
    },
    "data": [
        // Tickets found by the search...
    ]
}

GET /account/{id}/mailboxes

Retrieve all of the mailboxes attached to an account.

[
    {
        "id": 3,
        "account_id": 3,
        "type": "email",
        "address": "hello@help.besnappy.com",
        "display": "Snappy Help",
        "auto_responding": 0,
        "auto_response": "",
        "active": 1,
        "created_at": "2012-12-05 15:24:20",
        "updated_at": "2013-04-18 18:10:43",
        "custom_address": null,
        "theme": "snappy",
        "local_part": "hello"
    }
]

GET /account/{id}/staff

Retrieve all of the staff attached to an account.

[
    {
        "id": 3,
        "email": "ian@userscape.com",
        "sms_number": null,
        "first_name": "Ian",
        "last_name": "Landsman",
        "photo": null,
        "culture": "en",
        "notify": 1,
        "created_at": "2012-12-05 15:24:20",
        "updated_at": "2013-05-07 20:26:35",
        "signature": null,
        "tour_played": 1,
        "timezone": "America\/New_York",
        "notify_new": 1,
        "news_read_at": "2013-05-07 20:26:35",
        "username": "ian"
    }
]

GET /account/{id}/contacts/{id-or-email}

Retrieve a contact associated with an account.

[
    {
        "id": 1,
        "account_id": 1,
        "first_name": "Eugene",
        "last_name": "Haag",
        "value": "colleen.jenkins@example.com",
        "provider": "email",
        "created_at": "2013-12-02 14:55:27",
        "updated_at": "2013-12-02 14:55:27",
        "address": "colleen.jenkins@example.com"
    }
]

GET /mailbox/{id}/waiting

Retrieve all of the waiting tickets from a mailbox.

[
    {
        "id": 1,
        "account_id": 3,
        "mailbox_id": 3,
        "created_via": "email",
        "last_reply_by": "customer",
        "last_reply_at": 1368011747,
        "opened_by_staff_id": null,
        "opened_by_contact_id": 4,
        "opened_at": 1367934047,
        "status": "waiting",
        "first_staff_reply_at": "2013-05-07 13:41:06",
        "default_subject": "Re: Welcome to Snappy",
        "summary": "Message summary",
        "created_at": 1367934047,
        "updated_at": "2013-05-08 11:15:47",
        "unread": true,
        "tags": [
            "@ian"
        ],
        "contacts": [
            {
                "id": 4,
                "account_id": 3,
                "first_name": "John",
                "last_name": "Smith",
                "value": "john.smith@gmail.com",
                "provider": "email",
                "created_at": "2013-05-07 13:40:47",
                "updated_at": "2013-05-07 13:40:47",
                "type": "from"
            }
        ],
        "mailbox": {
        },
        "opener": {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47"
        }
    }
]

GET /account/{id}/waiting

Retrieve all of the waiting tickets from an account.

[
    {
        "id": 1,
        "account_id": 3,
        "mailbox_id": 3,
        "created_via": "email",
        "last_reply_by": "customer",
        "last_reply_at": 1368011747,
        "opened_by_staff_id": null,
        "opened_by_contact_id": 4,
        "opened_at": 1367934047,
        "status": "waiting",
        "first_staff_reply_at": "2013-05-07 13:41:06",
        "default_subject": "Re: Welcome to Snappy",
        "summary": "Message summary",
        "created_at": 1367934047,
        "updated_at": "2013-05-08 11:15:47",
        "unread": true,
        "tags": [
            "@ian"
        ],
        "contacts": [
            {
                "id": 4,
                "account_id": 3,
                "first_name": "John",
                "last_name": "Smith",
                "value": "john.smith@gmail.com",
                "provider": "email",
                "created_at": "2013-05-07 13:40:47",
                "updated_at": "2013-05-07 13:40:47",
                "type": "from"
            }
        ],
        "mailbox": {
        },
        "opener": {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47"
        }
    }
]

GET /mailbox/{id}/inbox

Retrieve all of the new and unassigned (inbox) tickets from a mailbox.

[
    {
        "id": 1,
        "account_id": 3,
        "mailbox_id": 3,
        "created_via": "email",
        "last_reply_by": "customer",
        "last_reply_at": 1368011747,
        "opened_by_staff_id": null,
        "opened_by_contact_id": 4,
        "opened_at": 1367934047,
        "status": "waiting",
        "first_staff_reply_at": "2013-05-07 13:41:06",
        "default_subject": "Re: Welcome to Snappy",
        "summary": "Message summary",
        "created_at": 1367934047,
        "updated_at": "2013-05-08 11:15:47",
        "unread": true,
        "tags": [
            "@ian"
        ],
        "contacts": [
            {
                "id": 4,
                "account_id": 3,
                "first_name": "John",
                "last_name": "Smith",
                "value": "john.smith@gmail.com",
                "provider": "email",
                "created_at": "2013-05-07 13:40:47",
                "updated_at": "2013-05-07 13:40:47",
                "type": "from"
            }
        ],
        "mailbox": {
        },
        "opener": {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47"
        }
    }
]

GET /account/{id}/inbox

Retrieve all of the new and unassigned (inbox) tickets from an account.

[
    {
        "id": 1,
        "account_id": 3,
        "mailbox_id": 3,
        "created_via": "email",
        "last_reply_by": "customer",
        "last_reply_at": 1368011747,
        "opened_by_staff_id": null,
        "opened_by_contact_id": 4,
        "opened_at": 1367934047,
        "status": "waiting",
        "first_staff_reply_at": "2013-05-07 13:41:06",
        "default_subject": "Re: Welcome to Snappy",
        "summary": "Message summary",
        "created_at": 1367934047,
        "updated_at": "2013-05-08 11:15:47",
        "unread": true,
        "tags": [
            "@ian"
        ],
        "contacts": [
            {
                "id": 4,
                "account_id": 3,
                "first_name": "John",
                "last_name": "Smith",
                "value": "john.smith@gmail.com",
                "provider": "email",
                "created_at": "2013-05-07 13:40:47",
                "updated_at": "2013-05-07 13:40:47",
                "type": "from"
            }
        ],
        "mailbox": {
        },
        "opener": {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47"
        }
    }
]

GET /mailbox/{id}/yours

Retrieve all of the waiting tickets that are assigned to you.

[
    {
        "id": 1,
        "account_id": 3,
        "mailbox_id": 3,
        "created_via": "email",
        "last_reply_by": "customer",
        "last_reply_at": 1368011747,
        "opened_by_staff_id": null,
        "opened_by_contact_id": 4,
        "opened_at": 1367934047,
        "status": "waiting",
        "first_staff_reply_at": "2013-05-07 13:41:06",
        "default_subject": "Re: Welcome to Snappy",
        "summary": "Message summary",
        "created_at": 1367934047,
        "updated_at": "2013-05-08 11:15:47",
        "unread": true,
        "tags": [
            "@ian"
        ],
        "contacts": [
            {
                "id": 4,
                "account_id": 3,
                "first_name": "John",
                "last_name": "Smith",
                "value": "john.smith@gmail.com",
                "provider": "email",
                "created_at": "2013-05-07 13:40:47",
                "updated_at": "2013-05-07 13:40:47",
                "type": "from"
            }
        ],
        "mailbox": {
        },
        "opener": {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47"
        }
    }
]

GET /account/{id}/yours

Retrieve all of the waiting tickets that are assigned to you across an entire account (all mailboxes)

[
    {
        "id": 1,
        "account_id": 3,
        "mailbox_id": 3,
        "created_via": "email",
        "last_reply_by": "customer",
        "last_reply_at": 1368011747,
        "opened_by_staff_id": null,
        "opened_by_contact_id": 4,
        "opened_at": 1367934047,
        "status": "waiting",
        "first_staff_reply_at": "2013-05-07 13:41:06",
        "default_subject": "Re: Welcome to Snappy",
        "summary": "Message summary",
        "created_at": 1367934047,
        "updated_at": "2013-05-08 11:15:47",
        "unread": true,
        "tags": [
            "@ian"
        ],
        "contacts": [
            {
                "id": 4,
                "account_id": 3,
                "first_name": "John",
                "last_name": "Smith",
                "value": "john.smith@gmail.com",
                "provider": "email",
                "created_at": "2013-05-07 13:40:47",
                "updated_at": "2013-05-07 13:40:47",
                "type": "from"
            }
        ],
        "mailbox": {
        },
        "opener": {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47"
        }
    }
]

GET /ticket/{id}

Retrieve the details of a ticket.

{
    "id": 1,
    "account_id": 3,
    "mailbox_id": 3,
    "created_via": "email",
    "last_reply_by": "customer",
    "last_reply_at": 1368011747,
    "opened_by_staff_id": null,
    "opened_by_contact_id": 4,
    "opened_at": 1367934047,
    "status": "waiting",
    "first_staff_reply_at": "2013-05-07 13:41:06",
    "default_subject": "Re: Welcome to Snappy",
    "summary": "Message summary",
    "created_at": 1367934047,
    "updated_at": "2013-05-08 11:15:47",
    "unread": true,
    "tags": [
        "@ian"
    ],
    "contacts": [
        {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47",
            "type": "from"
        }
    ],
    "mailbox": {
    },
    "opener": {
        "id": 4,
        "account_id": 3,
        "first_name": "John",
        "last_name": "Smith",
        "value": "john.smith@gmail.com",
        "provider": "email",
        "created_at": "2013-05-07 13:40:47",
        "updated_at": "2013-05-07 13:40:47"
    }
}

GET /ticket/{id}/notes

Get all of the notes attached to a ticket.

[
    {
        "id": 102,
        "account_id": 3,
        "ticket_id": 11232,
        "created_by_staff_id": null,
        "created_by_contact_id": 4,
        "scope": "public",
        "created_at": 1368011747,
        "updated_at": "2013-05-08 11:15:47",
        "content": "Note content...",
        "contacts": [
            {
                "id": 4,
                "account_id": 3,
                "first_name": "John",
                "last_name": "Smith",
                "value": "john.smith@gmail.com",
                "provider": "email",
                "created_at": "2013-05-07 13:40:47",
                "updated_at": "2013-05-07 13:40:47",
                "type": "from"
            }
        ],
        "attachments": [
        ],
        "creator": {
            "id": 4,
            "account_id": 3,
            "first_name": "John",
            "last_name": "Smith",
            "value": "john.smith@gmail.com",
            "provider": "email",
            "created_at": "2013-05-07 13:40:47",
            "updated_at": "2013-05-07 13:40:47"
        }
    },
]

POST /note

Send a new note to one of the account's mailboxes. A ticket will automatically be created.

Posting a note "from" a customer:

{
    "mailbox_id": 3,
    "subject": "Message Subject",
    "from": [
        {"name": "John Smith", "address": "john.smith@gmail.com"}
    ],
    "message": "Message Content"
}

Posting a note "to" a customer:

{
    "mailbox_id": 3,
    "staff_id": 2,
    "subject": "Message Subject",
    "to": [
        {"name": "John Smith", "address": "john.smith@gmail.com"}
    ],
    "message": "Message Content"
}

To attach a note to an existing ticket, just add the ticket nonce to the payload in the id slot:

{
    "id": "your-ticket-nonce",
    "mailbox_id": 3,
    "staff_id": 2,
    "subject": "Message Subject",
    "to": [
        {"name": "John Smith", "address": "john.smith@gmail.com"}
    ],
    "message": "Message Content"
}

To create a "private" note, set the scope on the JSON payload:

{
    "id": "your-ticket-nonce",
    "mailbox_id": 3,
    "staff_id": 2,
    "subject": "Message Subject",
    "to": [
        {"name": "John Smith", "address": "john.smith@gmail.com"}
    ],
    "message": "Message Content",
    "scope": "private"
}

POST /ticket/{id}/tags

Update the tags assigned to a ticket.

The POST request should contain a tags field which contains a JSON encoded list of tags.

{
    "tags": ["#tag1", "#tag2"]
}

PUT /ticket/{id}/status

Update the status of a ticket.

The PUT request should contain a status field.

{
    "status": "replied"
}

DELETE /ticket/{id}

Delete a ticket.

GET /account/{id}/documents

Retrieve all of the documents attached to an account.

[
    {
        "id": 60,
        "account_id": 3,
        "filename": "faq.png",
        "type": "image\/png",
        "size": 265420,
        "storage_key": "71be44f646d46af5023ec9dd21b732b4",
        "created_at": "2013-05-07 16:04:45",
        "updated_at": "2013-05-07 16:04:45"
    }
]

GET /account/{id}/document/{id}/download

Download a document.

POST /account/{id}/document

Upload a document to the given account.

The document should be attached to the POST as a file named document. You may optionally include a POST field named tags. When included, the tags field should be a JSON encoded list of tags.

GET /ticket/{id}/attachment/{attachment_id}/download

Download an attachment.

GET /account/{id}/wall

Read the latest 25 posts from the team wall. You pass a wall post ID in the query string to "paginate" results:

`GET /account/{id}/wall?after=405

POST /account/{id}/wall

{
    "content": "Post Content",
    "type": "post",
    "ticket": null,
    "note": null,
    "tags": ["foo", "bar"]
}

DELETE /account/{id}/wall/{post_id}

Delete a wall post.

POST /account/{id}/wall/{post_id}/comment

Comment on wall post. The comment content should be in a POST field named "content".

DELETE /account/{id}/wall/{post_id}/comment/{comment_id}

Delete a wall post comment.

POST /account/{id}/wall/{post_id}/like

Like a given wall post.

DELETE /account/{id}/wall/{post_id}/like

Unlike a given wall post.

Searching FAQs

GET /account/{id}/faqs/search?query=search&page=1

{
   "meta":{
      "total":2,
      "page":1
   },
   "data":[
      {
         "id":2,
         "account_id":1,
         "question":"Pricing and use of multiple accounts",
         "answer":"Snappy allows you to have multiple distinct accounts...",
         "created_at":"2014-07-21 20:22:12",
         "updated_at":"2014-07-21 20:22:12",
         "active":1
      },
      {
         "id":1,
         "account_id":1,
         "question":"How do I use the custom contact lookup application?",
         "answer":"The custom contact application allows you to load...",
         "created_at":"2014-07-21 20:22:12",
         "updated_at":"2014-07-21 20:22:12",
         "active":1
      }
   ]
}

Creating And Editing FAQs

GET /account/{id}/faqs

Get all of the FAQs for an account.

POST /account/{id}/faqs

Create a new FAQ.

Request:

{
    "title": "My FAQ",
    "url": "faq"
}

PUT /account/{id}/faqs/{faq_id}

Update an FAQ.

Request:

{
    "title": "My FAQ",
    "url": "faq"
}

DELETE /account/{id}/faqs/{faq_id}

Delete an FAQ.

Creating And Editing FAQ Topics

GET /account/{id}/faqs/{faq_id}/topics

Get all of the topics for an FAQ.

POST /account/{id}/faqs/{faq_id}/topics

Create a new FAQ topic.

Request:

{
    "topic": "My topic name."
}

PUT /account/{id}/faqs/{faq_id}/topics/{topic_id}

Update an FAQ topic.

Request:

{
    "topic": "My topic name."
}

DELETE /account/{id}/faqs/{faq_id}/topics/{topic_id}

Delete an FAQ topic.

Creating And Editing FAQ Questions

GET /account/{id}/faqs/{faq_id}/topics/{topic_id}/questions

Get all of the questions for a given topic.

POST /account/{id}/faqs/{faq_id}/topics/{topic_id}/questions

Create a new question for a topic.

{
    "question": "My question.",
    "answer": "My answer."
}

PUT /account/{id}/faqs/{faq_id}/topics/{topic_id}/questions/{question_id}

Update a question.

{
    "question": "My question.",
    "answer": "My answer."
}

PUT /account/{id}/faqs/{faq_id}/topics/{topic_id}/questions/{question_id}/topics

Update the topics a question is attached to.

{
    "topics": [1, 2, 3]
}

DELETE /account/{id}/faqs/{faq_id}/topics/{topic_id}/questions/{question_id}

Delete a question.