> ## Documentation Index > Fetch the complete documentation index at: https://docs.smokeball.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/api-docs/c916c683c136e-authentication-overview)). Make sure to [include the appropriate scopes](/docs/platform-docs/867hiv3k5bt1u-build-app#scopes) in your app settings before attempting any API requests. ## Example Request ```bash curl theme={"dark"} curl --request GET "https://api.smokeball.com/contacts/" \ --header "x-api-key: Y2xpZW50X2lkOmNsaWV" \ --header "Authorization: Bearer eyJraWQiOiJseVpBaHdjSW5UdVl6U" ``` ```json http theme={"dark"} { "method": "get", "url": "https://api.smokeball.com/contacts/", "headers": { "x-api-key": "Y2xpZW50X2lkOmNsaWV", "Authorization": "Bearer eyJraWQiOiJseVpBaHdjSW5UdVl6U..." } } ``` Client authentication key issued by Smokeball. Used to identify the application making the request. Example: `Y2xpZW50X2lkOmNsaWV` Bearer token for user authentication. Must be prefixed with `Bearer`. Example: `Bearer eyJraWQiOiJseVpBaHdjSW5UdVl6U...` **Response** ```json theme={"dark"} 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: ```json theme={"dark"} 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](/docs/platform-docs/4f56d789e123f-creating-app#app-type) 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](1-Authentication.md#2-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}](https://api.smokeball.com/\{accountId}/\{resource-path}) For example, using the contacts resource, a typical URL would be:\ [https://api.smokeball.com/contacts/](https://api.smokeball.com/contacts/)\ But for a server-to-server request specifying the `accountId: ea4ca7b9-b826-4840-a8k5-94e6c6937c65`, the URL becomes: ```bash curl theme={"dark"} curl --request GET "https://api.smokeball.com/ea4ca7b9-b826-4840-a8k5-94e6c6937c65/contacts/" \ --header "x-api-key: Y2xpZW50X2lkOmNsaWV" \ --header "Authorization: Bearer Y2xpZW50X2lkOmNsaWV" ``` ```json http theme={"dark"} { "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: ```json theme={"dark"} 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](/api-reference/firm-users/get-firm-staffuser-mappings) 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](/docs/api-docs/wivbkstcwngb5-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.