Skip to main content
All requests to the API require a valid api-key issued by Smokeball and access_token (see Authentication). Make sure to include the appropriate scopes in your app settings before attempting any API requests.

​
Example Request

curl --request GET "https://api.smokeball.com/contacts/" \
  --header "x-api-key: Y2xpZW50X2lkOmNsaWV" \
  --header "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
PropertyDescription
offsetThe number at which the results set begins
limitThe number of results in the response
sizeThe total number of results
firstA link to the first result set
nextA link to the next result set
lastA 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 accountsIt 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 --request GET "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts/" \
  --header "x-api-key: Y2xpZW50X2lkOmNsaWV" \
  --header "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.