Making Requests

Make requests to the API

All requests to the Smokeball API require a valid API key issued by Smokeball and an access token (see Authentication).

Make sure to include the appropriate scopes in your app settings before attempting any API requests.

Example Request

curl

curl --request GET "https://api.smokeball.com/contacts/" \
  --header "x-api-key: Y2xpZW50X2lkOmNsaWV" \
  --header "Authorization: Bearer eyJraWQiOiJseVpBaHdjSW5UdVl6U"

{
  "method": "get",
  "url": "https://api.smokeball.com/contacts/",
  "headers": {
    "x-api-key": "Y2xpZW50X2lkOmNsaWV",
    "Authorization": "Bearer eyJraWQiOiJseVpBaHdjSW5UdVl6U..."
  }
}

x-api-key · string · required

Client authentication key issued by Smokeball.

Used to identify the application making the request. Example: Y2xpZW50X2lkOmNsaWV

Authorization · string · required

Bearer token for user authentication.

Must be prefixed with Bearer.

Example: Bearer eyJraWQiOiJseVpBaHdjSW5UdVl6U...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "href": "https://api.smokeball.com/contacts",
  "offset": 0,
  "limit": 500,
  "size": 761,
  "first": {
    "href": "https://api.smokeball.com/contacts"
  },
  "next": {
    "href": "https://api.smokeball.com/contacts?limit=500&offset=500",
    "rel": "collection"
  },
  "last": {
    "href": "https://api.smokeball.com/contacts?limit=500&offset=500",
    "rel": "collection"
  },
  "value": [
    {
      "href": "https://api.smokeball.com/contacts/323f9755-045a-4b68-a536-eb566b8428ff",
      "id": "323f9755-045a-4b68-a536-eb566b8428ff",
      "groupOfPeople": {
        "people": [
          {
            "href": "https://api.smokeball.com/contacts/a1d868da-1243-4b9f-a8e3-cfc5c4abda50"
          },
          {
            "href": "https://api.smokeball.com/contacts/ea4ca7b9-b826-4840-a8b5-94e0c6977c65"
          }
        ],
        "residentialAddress": {
          "addressLine1": "1247 N Clark Street",
          "city": "Chicago",
          "state": "IL",
          "zipCode": "60607",
          "county": "Cook",
          "country": "United States"
        }
      }
    }
  ]
}

Paged Responses

You will notice that some requests will have the optional parameters limit and offset. These are used to control how many results are returned in a request that returns a list of results.

In the response above, you can see the details of the paging properties in the first section of the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "href": "https://api.smokeball.com/contacts",
  "offset": 0,
  "limit": 500,
  "size": 761,
  "first": {
    "href": "https://api.smokeball.com/contacts"
  },
  "next": {
    "href": "https://api.smokeball.com/contacts?limit=500&offset=500",
    "rel": "collection"
  },
  "last": {
    "href": "https://api.smokeball.com/contacts?limit=500&offset=500",
    "rel": "collection"
  }
}

Paging Properties

Property	Description
offset	The number at which the results set begins
limit	The number of results in the response
size	The total number of results
first	A link to the first result set
next	A link to the next result set
last	A link to the last result set

By default, the limit will be set to a maximum of 500 results.

Server-to-Server requests

The details below apply only if your Client Credentials Grant allows access to multiple accounts

It does not apply for Private Apps created via the Developer Console, which are restricted to a single account.

If your app was created from the Developer Console, you can ignore this section.

When using the Client Credentials Grant to perform server-to-server requests, and your credentials are authorized to access more than one account, you must explicitly specify which account you are targeting by prefixing the URL with the accountId in this format:

https://api.smokeball.com/{accountId}/{resource-path}

For example, using the contacts resource, a typical URL would be:
https://api.smokeball.com/contacts/
But for a server-to-server request specifying the accountId: ea4ca7b9-b826-4840-a8k5-94e6c6937c65, the URL becomes:

curl

curl --request GET "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts/" \
  --header "x-api-key: Y2xpZW50X2lkOmNsaWV" \
  --header "Authorization: Bearer Y2xpZW50X2lkOmNsaWV"

{
  "method": "get",
  "url": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts/",
  "headers": {
    "x-api-key": "Y2xpZW50X2lkOmNsaWV",
    "Authorization": "Bearer Y2xpZW50X2lkOmNsaWV"
  }
}

Response

Note: All links in the response will include the accountId prefix:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "href": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts",
  "offset": 0,
  "limit": 500,
  "size": 761,
  "first": {
    "href": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts"
  },
  "next": {
    "href": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts?limit=500&offset=500",
    "rel": "collection"
  },
  "last": {
    "href": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts?limit=500&offset=500",
    "rel": "collection"
  },
  "value": [
    {
      "href": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts/323f9755-045a-4b68-a536-eb566b8428ff",
      "id": "323f9755-045a-4b68-a536-eb566b8428ff",
      "groupOfPeople": {
        "people": [
          {
            "href": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts/a1d868da-1243-4b9f-a8e3-cfc5c4abda50"
          },
          {
            "href": "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts/ea4ca7b9-b826-4840-a8b5-94e0c6977c65"
          }
        ],
        "residentialAddress": {
          "addressLine1": "1247 N Clark Street",
          "city": "Chicago",
          "state": "IL",
          "zipCode": "60607",
          "county": "Cook",
          "country": "United States"
        }
      }
    }
  ]
}

Acting on behalf of a user

Because server-to-server requests are not performed using a user token there is no userId associated with each request. A userId is necessary for permission checking or ensuring that the UI reflects the change done by the specified user.

To act on behalf of a certain user simply supply the UserId header with your requests. The value must be that of a User in the firm.

Tracking your requests

Since all POST/PUT requests are handled asynchronously by the Smokeball API, it is useful to be able to track the changes especially when using Webhooks. This is acheived by supplying the RequestId header with your requests.

If the RequestId header is supplied, it will be returned as a response header for every request you make. It will also be included in all webhook callbacks so you can track what data was impacted by your request.