Bans

You can use the API to get or set Ban information.

JSON Format

Bans are represented as JSON objects with the following attributes.

Name Type Read-only Description
id integer yes The ID of the ban
type string yes The type of the ban
visitor_id string yes The ID of the banned visitor
visitor_name string yes The display name of the banned visitor
ip_address string yes The IP address of the banned visitor
reason string yes The reason for the ban

Get All Bans

  • GET /api/v2/bans
  • GET /api/v2/bans?since_id=100&limit=100
  • GET /api/v2/bans?max_id=150

Lists the bans for the account. Returns up to 1000 results per page. See Pagination below.

Pagination

This endpoint uses cursor-based pagination. The records are ordered sequentially by record id. The max_id and since_id parameters act as separate cursors that track the record ids in the recordset. The max_id cursor moves backward through the recordset, with the record ids getting smaller. The since_id cursor moves forward, with the record ids getting larger.

  • Use the max_id parameter to paginate backward through the recordset. Example: "Get the previous 200 records, ending with and including the max_id record."

    "https://www.zopim.com/api/v2/bans?max_id=10&limit=200"

  • Use the since_id parameter to paginate forward through the recordset. Example: "Get the next 200 records, starting with and including the since_id record."

    "https://www.zopim.com/api/v2/bans?since_id=10&limit=200"

The next page can be retrieved by computing the next since_id by adding 1 to the ID of the last record in the current set, and specifying that as the since_id in the next request. Similarly, the previous page can be retrieved by making a request that species a max_id that is 1 less than the first element of the current record set.

Additionally, the next page and the previous page paths will be available as headers in the response.

If any of the pagination parameters (since_id, max_id, limit) are present, the default number of results is 10, but you can change it with the limit parameter. If none of the pagination parameters are present, the entire record set is returned.

Zendesk Chat recommends using pagination wherever possible. Non-paginated queries will be deprecated in subsequent releases of the API.

Allowed for
  • Owner
  • Administrator
Using cURL
curl "https://www.zopim.com/api/v2/bans?since_id=5&limit=2" \
  -v -u {email_address}:{password}

Note: In this example, you must enclose the URL in quotes because of the pagination parameters.

Example Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Next-Page: /api/v2/bans?since_id=9&limit=2
X-Previous-Page: /api/v2/bans?max_id=4&limit=2

{
  "visitor": [
    {
      "visitor_id": "2",
      "reason": "Spammer",
      "visitor_name": "John",
      "id": 5
    }
  ],
  "ip_address": [
    {
      "ip_address": "242.211.134.60",
      "reason": "Spammer",
      "id": 8
    }
  ]
}

Get Banned IP Addresses

GET /api/v2/bans/ip

Fetches a list of banned visitor IP Addresses for your account.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/bans/ip \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

[
  "155.69.127.97",
  "155.69.127.98"
]

Get Ban

GET /api/v2/bans/{ban_id}

Fetches a ban by its ID.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/bans/{ban_id} \
  -v -u {email_address}:{password}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ip_address": "87.230.12.41",
  "visitor_id": "",
  "visitor_name": "",
  "reason": "Spammer",
  "type": "I",
  "id": 1
}

Create Ban

POST /api/v2/bans

Allows an account owner/administrator to create a ban, either by visitor ID or by IP address.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/bans \
  -d '{
        "visitor_id" : "12345",
        "reason" : "Spammer"
      }' \
  -v -u {email_address}:{password} \
  -X POST -H "Content-Type: application/json"

or

curl https://www.zopim.com/api/v2/bans \
  -d '{
        "ip_address" : "192.123.123.5",
        "reason" : "Spammer"
      }' \
  -v -u {email_address}:{password} \
  -X POST -H "Content-Type: application/json"
Example Responses
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : 1
  "visitor_id" : "12345",
  "visitor_name" : "Agent Smith",
  "type" : "V",
  "reason" : "Spammer",
  "ip_address" : ""
}

and

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : 2
  "ip_address" : "192.123.123.5",
  "type" : "I",
  "reason" : "Spammer",
  "visitor_id" : "",
  "visitor_name" : ""
}

Delete Ban

DELETE /api/v2/bans/{ban_id}

Allows an account owner to delete a ban.

Allowed for
  • Owner
  • Administrator
Using cURL
curl https://www.zopim.com/api/v2/bans/{ban_id} \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content