No description, website, or topics provided.
Latest commit 3552688 Jun 13, 2017 @njovin njovin committed on GitHub Create GET_list.md
Permalink
Failed to load latest commit information.
.postman_tutorial Update README.md Apr 6, 2016
accounts Update GET_list.md May 18, 2016
automations Update README.md Jun 2, 2017
available_phone_numbers Update GET_list.md May 18, 2016
channel_types Update README.md Mar 21, 2017
conditions initial bit of contact group documentation May 5, 2017
contact_channels Create DELETE_id.md Oct 13, 2016
contact_custom_fields Update automations/GET_list.md, contact_custom_fields/GET_list.md, co… May 17, 2017
contact_groups add contact group listing May 5, 2017
contact_services Update GET_list.md Aug 1, 2016
contacts Create GET_list.md Jun 13, 2017
custom_field_values Update POST_create_id.md Sep 25, 2016
events Update events/GET_id.md and events/GET_list.md May 17, 2017
field_options Update README.md Sep 29, 2016
labels Update GET_list.md Oct 13, 2016
messages Create POST_create.md Jun 13, 2017
notifications push notification title update May 22, 2016
plans Delete GET_id.md Sep 19, 2016
receive_notifications Create README.md Jun 10, 2016
service_addresses Create README.md Sep 21, 2015
service_channels auth class updates May 18, 2016
service_settings Update POST_create.md Sep 19, 2016
services Update PUT_update_id.md Jul 26, 2016
settings_fields remove a bunch of object verbiage Sep 22, 2015
templates auth class updates May 18, 2016
time_zones auth class updates May 18, 2016
users Update PUT_update_avatar.md Apr 11, 2017
CHANGELOG.md Update CHANGELOG.md Feb 25, 2016
README.md Update README.md Apr 20, 2017
error_codes.md Update error_codes.md May 23, 2017
resource_overview.md Update resource_overview.md Sep 21, 2015

README.md

Zingle REST API

Overview

Zingle is a multi-channel communications platform that allows the sending, receiving and automating of conversations between a Business and a Customer. Zingle is typically interacted with by Businesses via a web browser to manage these conversations with their customers. The Zingle API provides functionality to developers to act on behalf of either the Business or the Customer. The Zingle iOS SDK provides mobile application developers an easy-to-use layer on top of the Zingle API.

Tutorial

We provide a Postman collection with a set of requests that introduce the basic concepts of the API. You will need an existing Zingle account with API access to run this tutorial. The Postman collection and more information are available here.

Support

For API support, please email api.support@zingle.me.

Authentication

Access to the API is granted by providing your username and password using HTTP basic authentication. The username and password used, is the same username and password you use to access the Zingle web interface.

There are two classes of users that have access to the API - "account" class users and "contact" class users. By default, all users have "contact" class access. "Account" class access must be requested from Zingle support. A contact class user is unable to access many API resources and must include a x-zingle-contact-id header containing the ID of the contact the request is being made on behalf of in most requests. See the "User Authorization Classes" section of each API call's documentation for details.

You may check the current user's class by issuing a GET request to the API's root URL:

GET https://api.zingle.me/v1/

{
    "status": {
        "text": "OK",
        "status_code": 200,
        "description": null
    },
    "auth": {
        "id": "4c11f5e3-50b6-4995-b471-b8ef0015488d",
        "email": "joe@example.com",
        "first_name": "Joe",
        "last_name": "Smith",
        "title": null,
        "authorization_class": "contact"
    }
}

API Versioning

The first part of the URI path specifies the API version you wish to access in the format v{version_number}.

For example, version 1 of the API (most current) is accessible via:

https://api.zingle.me/v1/

HTTP requests

All API requests are made by sending a secure HTTPS request using one of the following methods, depending on the action being taken:

  • POST Create a resource
  • PUT Update a resource
  • GET Get a resource or list of resources
  • DELETE Delete a resource

For PUT and POST requests the body of your request may include a JSON payload, and the URI being requested may include a query string specifying additional filters or commands, all of which are outlined in the following sections.

HTTP Responses

Each response will include a status object and (if successful) a result (result will be an object for single-record queries and an array for list queries). The status object contains an HTTP status_code, text, description, error_code (if an error occurred - see Error Codes) and pagination info about the result. The result contains the result of a successful request. For example, a request to the /services/ resource might return this:

{
    "status": 
    {
        "text":           "OK",        
        "status_code":    200,         
        "description":    null,        
        "sort_field":     "display_name", 
        "sort_direction": "asc",       
        "page":           1,           
        "page_size":      10,          
        "total_pages":    1,           
        "total_records":  8,           
    },
    "result": 
    [
      {
        "id": "aff7bc93-6e28-4e70-8770-defa35cdfc1f",
        "display_name": "My test API service",
        "time_zone": "America/Los_Angeles",
        "created_at": 1429034365,
        "updated_at": 1439228868,
        "account": {
            "id": "2c89b706-47f2-471d-8e1b-4a180b448838",
            "display_name": "Developer Account",
            "term_months": 1,
            "current_term_start_date": 1433116800,
            "current_term_end_date": null,
            "created_at": 1380312314,
            "updated_at": 1438919580
        },
        "plan": {
            "id": "a0eb6d49-caa8-4bd2-ae15-acb529a2ca98",
            "code": "zingle_basic",
            "term_months": 1,
            "monthly_or_unit_price": 0,
            "setup_price": 0,
            "display_name": "Zingle Basic",
            "is_printer_plan": false
        },
        "channels": [
          {
              "id": "d9f91fdb-bbdb-442d-bbac-99fc76263654",
              "display_name": null,
              "value": "+17245551212",
              "formatted_value": "(724) 555-1212",
              "country": "US",
              "is_default_for_type": true,
              "channel_type": {
                  "id": "0e3d71ee-9518-4b9b-b95a-2ea251829887",
                  "type_class": "PhoneNumber",
                  "display_name": "Phone Number",
                  "inbound_notification_url": null,
                  "outbound_notification_url": null,
                  "allow_communications": true
              }
          }
        ],
        "channel_types": [
          {
              "id": "0e3d71ee-9518-4b9b-b9a5a-dea251829887",
              "type_class": "PhoneNumber",
              "display_name": "Phone Number",
              "inbound_notification_url": null,
              "outbound_notification_url": null,
              "allow_communications": true
          }
        ],
        "service_address": {
            "address": "123 Zingle Blvd.",
            "city": "San Diego",
            "state": "CA",
            "country": "US",
            "postal_code": "92129"
        },
        "customFieldValues": []
      }
    ]
  }

HTTP Response Codes

Each response will be returned with one of the following HTTP status codes:

  • 200 OK The request was successful
  • 400 Bad Request There was a problem with the request (security, malformed, data validation, etc.)
  • 401 Unauthorized The supplied API credentials are invalid
  • 403 Forbidden The credentials provided do not have permission to access the requested resource
  • 404 Not found An attempt was made to access a resource that does not exist in the API
  • 405 Method not allowed The resource being accessed doesn't support the method specified (GET, POST, etc.).
  • 500 Server Error An error on the server occurred

Request Modifiers

Request modifiers may be included in the request URI query string. The following modifiers are available throughout the API. Other resource-specific modifiers are covered under the specific resource documentation sections.

  • page The page number in the result set to return (default 1)
  • page_size The number of records to return per page (default 10, max 1000)
  • sort_field field to sort the results by
  • sort_direction asc (default) or desc
  • sort_fields Specify multiple fields to sort by seperated by commas. Optionally append with a space and a direction e.g. "event_id asc"

Record Filtering

In addition to the request modifiers, record filters may also be specified in the query string. Exactly which fields may be filtered and sorted on for each resource are covered in the resource sections. A simple filter for services in California would look like this:

https://api.zingle.me/v1/services?state=CA

Wildcards are also supported for some fields by using an asterisk in the filter. The following would return any services with display anmes containing 'foo':

https://api.zingle.me/v1/services?display_name=*foo*

Some values, such as dates, support range selection by using 'greater_than' and 'less_than' functions. All messages sent from January 1, 2015 at 8:00AM to February 1, 2015 at 8:00AM could be retrieved with the following query:

https://api.zingle.me/v1/services/f762cdf9-6b0c-4563-a774-3e9d86f908f9/messages?communication_direction=inbound&created_at=greater_than(1420099200000),less_than(1422777600000)

Note that all dates are in the form of Unix timestamps (seconds since January 1, 1970) and returned in GMT - you will have to account for time zone adjustment depending on your client's location.

Resources

For a description of the available resources see the Resource Overview.

General

Accounts

Services

Channel Types

Service Channels

Contacts

Contact Channels

Messages

Contact Custom Fields

Labels

Templates

Automations